Using the Google Books API

I recently started playing around with the Google Books API and ran into some issues that (at least to me) were not clear in the documentation.

Authentication

Perhaps 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 :

#!/bin/bash
read -p 'Username: ' username
stty -echo
read -p "Password: " password; echo
stty 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: "
cat ~/.booksAuthToken

The second script is called getBooksFeed.sh and is a convenience wrapper to make it easier to access the feeds :

#!/bin/bash
authToken=`cat ~/.booksAuthToken`
url="http://books.google.com/books/feeds/users/me/$1"
curl --silent --header "Authorization: GoogleLogin Auth=$authToken" -L "$url" | tidy -xml -indent -quiet
echo ""

To use these scripts, first use getAuthToken.sh to get your authorization token. Then you can access the Books feeds by using getBooksFeed.sh.

For example, you can get a list of your collections with :

getBooksFeed.sh collections

and a list of books with :

getBooksFeed.sh volumes

Bookshelves

In 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"

Unfortunately, the documentation for using Google Books API doesn't talk about how to access individual bookshelves. For example, to access your library, both the Google Books API Developer's Guide and the Google Books Data API : Reference Guide say to use :

http://books.google.com/books/feeds/users/me/collections/library/volumes

The 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>/volumes

which 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/collections

This 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 bookshelves

To search your library, the Developer's Guide says to use :

http://books.google.com/books/feeds/users/me/collections/library/volumes?q=bear

But 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=bear

which 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=bear

where <id> is the ID of the bookshelf to search.

Summary

Note: 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 :

collections

To get information about a specific bookshelf :

collections/<id>

To get a list of all the books in a bookshelf :

collections/<id>/volumes

To get a list of all your books :

volumes

To search all your books (in all bookshelves) :

volumes?<search-term>

To search within a specific bookshelf :

collections/<id>/volumes?<search-term>