AuthenticationPerhaps it's just me, but I found the Authenticating section of the Books API to be somewhat difficult to follow. This is unfortunate since this step is absolutely necessary to do anything with the API.
I found the Getting Started page for accessing the Google Website Optimizer API to be a lot easier to deal with. These instructions were based on another document : Using cURL to interact with Google Data services. Basically, you create 2 scripts : one to record your authorization token and another to access the feeds using this token.
I've modified these scripts to work with the Books API. Note that these are shell scripts that work on Linux and Macintosh. For Windows, you'd need to create equivalent batch files to replicate this.
The first script is called getAuthToken.sh and is used to request and record your authorization token :
The second script is called getBooksFeed.sh and is a convenience wrapper to make it easier to access the feeds :
read -p 'Username: ' username
read -p "Password: " password; echo
curl -d "accountType=GOOGLE&Email=$username&Passwd=$password&source=books-feed&service=print" https://www.google.com/accounts/ClientLogin | grep 'Auth=' | sed s/Auth=// > ~/.booksAuthToken
echo "Token: "
To use these scripts, first use getAuthToken.sh to get your authorization token. Then you can access the Books feeds by using getBooksFeed.sh.
curl --silent --header "Authorization: GoogleLogin Auth=$authToken" -L "$url" | tidy -xml -indent -quiet
For example, you can get a list of your collections with :
getBooksFeed.sh collectionsand a list of books with :
BookshelvesIn January of this year, the Google Books team introduced "bookshelves", which replace the labels that could previously be added to books. With this change, your "My Library" now has a set of shelves. Individual books in your collection can belong to one or more bookshelves.
There are 5 bookshelves created automatically for you (and you can't delete them if you don't want them. Grrr..). These default bookshelves are :
- "Reviewed" - This is your public bookshelf. It cannot be made private, so anything you place here will always be visible to everyone.
- "Favorites" - This is your default bookshelf.
- "Reading now"
- "To read"
- "Have read"
http://books.google.com/books/feeds/users/me/collections/library/volumesThe problem is that this URL doesn't return all of the books in the user library — it only returns the books in the default bookshelf ("Favorites").
To get a list of the books in a different bookshelf, you need to use the following URL :
http://books.google.com/books/feeds/users/me/collections/<id>/volumeswhich requires that you know the <id> of the bookshelf you want to search. You can get these IDs by requesting a list of bookshelves :
http://books.google.com/books/feeds/users/me/collectionsThis will return a list of all bookshelves in the user library and each entry will contain a URL that contains the bookshelf ID. The pre-defined shelves have numbers between 0 and 5, whereas user-defined shelves seem to start at 1001.
For my account, 0 = "Favorites", 2 = "To read", 3 = "Reading now", 4 = "Have read", and 5 = "Reviewed". Bookshelf ID = 1 doesn't seem to be defined.
So, using "library" as the <id> appears to be an alias for bookshelf "0" which is somewhat misleading since "library" implies all bookshelves, whereas it actually returns only those volumes in the "Favorites" bookshelf. My guess is that this is an artifact of the old pre-bookshelf days that didn't quite translate well.
Searching bookshelvesTo search your library, the Developer's Guide says to use :
http://books.google.com/books/feeds/users/me/collections/library/volumes?q=bearBut this will only search the default ("Favorites") bookshelf. The proper way to search your entire library is to use :
http://books.google.com/books/feeds/users/me/volumes?q=bearwhich will search all of your bookshelves.
To search a single bookshelf, you can use :
http://books.google.com/books/feeds/users/me/collections/<id>/volumes?q=bearwhere <id> is the ID of the bookshelf to search.
SummaryNote: This section gives the parameter that you would pass to the getBooksFeed.sh script. If you need the full URL for these feeds, add the following at the beginning :
http://books.google.com/books/feeds/users/me/To get a list of all your bookshelves :
collectionsTo get information about a specific bookshelf :
collections/<id>To get a list of all the books in a bookshelf :
collections/<id>/volumesTo get a list of all your books :
volumesTo search all your books (in all bookshelves) :
volumes?<search-term>To search within a specific bookshelf :