[go: up one dir, main page]
My favorites ▼ | English ▼ | Sign in

Developer's Guide, Protocol

Important: The Google GData Books API is deprecated as of May 26, 2011 and will be fully retired on December 1, 2011. Therefore, we encourage you to move to the new Books API.

The Data API allows client applications to view and update Google Books content in the form of Google Data API feeds.

Your client application can use the Data API to issue full-text searches for books and to retrieve standard book information, ratings, and reviews. You can also access individual users' library collections and public reviews. Finally, your application can submit authenticated requests to enable users to create and modify library collections, ratings, labels, reviews, and other account-specific entities.

In addition to providing some background on the capabilities of the Data API, this document provides examples of basic Data API interactions using raw XML and HTTP. After reading this document, you may want to learn more about interacting with the API using our client libraries by reading the programming-language-specific sections of this developer's guide.

Contents

  1. Audience
  2. Getting started
    1. Creating a Google Books account
  3. Authenticating to the Google Books service
    1. AuthSub proxy authentication
    2. ClientLogin username/password authentication
  4. Setting user location
  5. Searching for books
    1. Example search result feed
    2. Partner Co-Branded Search
  6. Using community features
    1. Adding a rating
    2. Reviews
      1. Adding a review
      2. Editing a review
    3. Labels
      1. Submitting a set of labels
      2. Editing labels
    4. Retrieving annotations: reviews, ratings, and labels
  7. Book collections and My Library
    1. Retrieving books in a user's library
      1. Retrieving all books in a user's library
      2. Searching for books in a user's library
    2. Updating books in a user's library
      1. Adding a book to a library
      2. Removing a book from a library
  8. Understanding Data API error messages

Audience

This document is intended for programmers who want to write client applications that can interact with Google Books using XML and HTTP.

This document assumes that you understand the general ideas behind the Google Data APIs protocol, and that you're familiar with Google Books and its My Library features.

If you're using a UNIX system and you want to try the examples in this document without writing any code, you may find the UNIX command-line utilities curl or wget useful; for more information, see the manual pages for those utilities.

For Data API reference information, see the Protocol reference guide.

Getting started

Creating a Google Books account

For testing purposes, you may want to create a Google Books library. Data API uses Google Accounts, so if you already have a Google account, you can use the My Library features with that account.

Authenticating to the Data API service

You can access both public and private feeds using the Data API. Public feeds don't require any authentication, but they are read-only. If you want to modify user libraries, submit reviews or ratings, or add labels, then your client needs to authenticate before requesting private feeds. It can authenticate using either of two approaches: AuthSub proxy authentication or ClientLogin username/password authentication.

For more information about authentication with Google Data APIs in general, see the authentication documentation.

Most of the samples in subsequent sections of this document assume you're supplying the appropriate authentication.

AuthSub proxy authentication

AuthSub proxy authentication is used by web applications that need to authenticate their users to Google Accounts. The website operator and the client code don't have access to the username and password for the Google Books user; instead, the client obtains special AuthSub tokens that allow the client to act on a particular user's behalf. For more detailed information, see the AuthSub documentation.

When a user first visits your application, they have not yet been authenticated. In this case, you need to display some information and a link directing the user to a Google page to authenticate your request for access to their account.

The following query parameters are included in the AuthSubRequest URL:

next
The URL of the page that Google should redirect the user to after authentication.
scope
Indicates that the application is requesting a token to access Data API feeds. The scope string to use is http://www.google.com/books/feeds/ (URL-encoded, of course).
secure
Indicates whether the client is requesting a secure token.
session
Indicates whether the token returned can be exchanged for a multi-use (session) token.

The AuthSubRequest URL might look like this:

https://www.google.com/accounts/AuthSubRequest?scope=http%3A%2F%2Fwww.google.com%2Fbooks%2Ffeeds%2F&session=1&secure=0&next=http%3A%2F%2Fwww.example.com%2Fwelcome.html

The user follows the link to Google's site and authenticates to their Google Account.

After the user authenticates, the AuthSub system redirects them to the URL you specified in the next query parameter of the AuthSubRequest URL. The AuthSub system appends an authentication token to that URL, as the value of the token query parameter. For example:

http://www.example.com/welcome.html?token=yourAuthToken

This token value represents a single-use AuthSub token. In this example, since session=1 was specified, this token can be exchanged for an AuthSub session token by calling the AuthSubSessionToken service with the single-use token in an Authorization header, as follows:

GET /accounts/AuthSubSessionToken HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: AuthSub token="yourAuthToken"
User-Agent: Java/1.5.0_06
Host: www.google.com
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive

The AuthSubSessionToken service response includes a Token header that contains the session token and an Expiration header that indicates how long the token will remain valid.

Your application can then use the session token value in the Authorization header of subsequent interactions with the Data API.

Here's an example of an HTTP request, containing a non-secure token, that you might send to the Data API:

GET http://www.google.com/books/feeds/users/me/volumes HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: AuthSub token="yourSessionToken"
User-Agent: Java/1.5.0_06
Host: www.google.com
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive

ClientLogin username/password authentication

Use ClientLogin authentication if your client is a standalone, single-user "installed" client (such as a desktop application). To request an authentication token using the ClientLogin mechanism, send a POST request to the following URL:

https://www.google.com/accounts/ClientLogin

The POST body should contain a set of query parameters that look like parameters passed by an HTML form, using the application/x-www-form-urlencoded content type. These parameters are:

accountType
Type of account to be authenticated. The default is GOOGLE; if you want to support Google Apps users, use HOSTED_OR_GOOGLE.
Email
The user's email address.
Passwd
The user's password.
service
The Data API service name is print. (For other service names, see the service name list.)
source
Identifies your client application. Should take the form companyName-applicationName-versionID.

For more information about the parameters, see the Authentication for Installed Applications document.

If the authentication request fails, then the server returns an HTTP 403 Forbidden status code.

If it succeeds, then the server returns an HTTP 200 OK status code, plus three long alphanumeric codes in the body of the response: SID, LSID, and Auth. The Auth value is the authorization token that you'll send to Data API with each of your subsequent volumes-feed requests, so keep a copy of that value. You can ignore the SID and LSID values.

Since all requests to private feeds require authentication, you have to set the Authorization header in all subsequent interactions with Data API, using the following format:

Authorization: GoogleLogin auth=yourAuthToken

Where yourAuthToken is the Auth string returned by the ClientLogin request.

For more information about ClientLogin authentication, including sample requests and responses, see the Authentication for Installed Applications documentation.

Note: Use the same token for all requests in a given session; don't acquire a new token for each Data API request.

Setting user location

Google Books respects copyright, contract, and other legal restrictions associated with the end user's location. As a result, some users may not be able to access book content from certain countries. For example, certain books are only "previewable" in the United States; we omit such books' preview links for users outside that country.

To ensure that your application's users receive accurate and consistent results, we recommend that you include the end user's IP address in every query to the Data API API. The user's IP address allows Google Books to determine with high accuracy the country where the user is located, which in turn allows Google Books to accurately determine what content can be served to the user. This is the same technique we use in the Google Books GUI to determine whether a preview is served to a particular user.

The Data API provides only search results--pointers to the desired books--which are accessible from anywhere in the world. Thus, if you show results to the user that includes books the user can't view, the user is likely to be frustrated or confused. So please provide the user's IP address when querying, to avoid showing the user results that they can't view.

To send the user's IP address with a query, simply add or modify the X-Forwarded-For header in your HTTP requests:

X-Forwarded-For: user's IP address

By default, the API results indicate restrictions based on your server or client application's IP address.

Searching for books

The Data API provides a number of feeds that list collections of books.

The most common action is to retrieve a list of books that match a search query. To do so, submit an HTTP GET request to the following URL, appending the appropriate query parameters to your request:

http://books.google.com/books/feeds/volumes

Note that Google Books often uses the term "volume" to refer to a book, so the volumes feed is a feed of books.

The following example searches for the second set of 10 books whose metadata or text matches the query term "football" but doesn't match the query term "soccer":

http://books.google.com/books/feeds/volumes?
    q=football+-soccer
    &start-index;=11
    &max-results;=10

After you send the GET request, Data API may return a redirect, depending on various factors. If so, send another GET request to the redirect URL.

When you send that GET request, Data API returns an HTTP 200 OK status code and a feed containing a list of books that matched your query.

Note: Since Google Books results are public, you can issue a Data API query without authentication.

The Data API supports the following query parameters:

q
Specifies a search query term. Google Books searches all book metadata and full text for books matching the term. Book metadata includes titles, keywords, descriptions, author names, and subjects.

Note that any spaces, quotes or other punctuation in the parameter value must be URL-escaped. (Use a plus (+) for a space.)

To search for an exact phrase, enclose the phrase in quotation marks. For example, to search for books matching the phrase "spy plane", set the q parameter to %22spy+plane%22.

You can also use any of the advanced search operators supported by Google Books. For example, jane+austen+-inauthor:austen returns matches that mention (but are not authored by) Jane Austen.
start-index
Specifies the index of the first matching result that should be included in the result set. This parameter uses a one-based index, meaning the first result is 1, the second result is 2 and so forth. This parameter works in conjunction with the max-results parameter to determine which results to return. For example, to request the third set of 10 results—results 21-30—set the start-index parameter to 21 and the max-results parameter to 10.

Note: This isn't a general cursoring mechanism. If you first send a query with ?start-index=1&max-results;=10 and then send another query with ?start-index=11&max-results;=10, the service cannot guarantee that the results are equivalent to ?start-index=1&max-results;=20, because insertions and deletions could have taken place in between the two queries.

max-results
Specifies the maximum number of results that should be included in the result set. This parameter works in conjunction with the start-index parameter to determine which results to return. The default value of this parameter is 10 and the maximum value is 20.
min-viewability
Allows you to filter the results according to the books' viewability status. This parameter accepts one of three values: noview (the default, returning all matching books regardless of viewability), partial (returning only books that the user can preview or view in their entirety), or full (returning only books that the user can view in their entirety).

Note that viewability restrictions vary according to the user's location. To ensure your users get accurate results, we recommend that you pass the end-user IP header with every HTTP request.

Note that these search query parameters can also be appended to other types of feed requests. For example, as described in the Searching for books in a user's library section, you can retrieve books in a specific user's library that match a particular keyword.

Example search result feed

The following is an example of the books feed returned for a search with only one result.

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"
      xmlns:gbs="http://schemas.google.com/books/2008"
      xmlns:dc="http://purl.org/dc/terms"
      xmlns:gd="http://schemas.google.com/g/2005">
  <id>http://www.google.com/books/feeds/volumes</id>
  <updated>2008-08-12T23:25:35.000</updated>
  <category scheme="http://schemas.google.com/g/2005#kind"
      term="http://schemas.google.com/books/2008#volume"/>
  <title type="text">Search results for it is a truth universally acknowledged</title>
  <link rel="alternate"
      type="text/html"
      href="http://www.google.com"/>
  <link rel="http://schemas.google.com/g/2005#feed"
      type="application/atom+xml"
      href="http://www.google.com/books/feeds/volumes"/>
  <link rel="self"
      type="application/atom+xml"
      href="http://www.google.com/books/feeds/volumes?q=IT+IS+A+TRUTH+universally+acknowledged"/>
  <link rel="next"
      type="application/atom+xml"
      href="http://www.google.com/books/feeds/volumes?q=IT+IS+A+TRUTH+universally+acknowledged&start-index=11&max-results=10"/>
  <author>
    <name>Google Books</name>
    <uri>http://www.google.com</uri>
  </author>
  <generator version="beta">Data API</generator>
  <openSearch:totalResults>597</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>20</openSearch:itemsPerPage>
  <entry>
    <id>http://www.google.com/books/feeds/volumes/8cp-Z_G42g4C</id>
    <category scheme="http://schemas.google.com/g/2005#kind"
          term="http://schemas.google.com/books/2008#volume"/>
    <title type="text">Pride and Prejudice</title>
    <link rel="http://schemas.google.com/books/2008/thumbnail"
          type="image/jpeg"
          href="http://bks8.books.google.com/books?id=8cp-Z_G42g4C&printsec=frontcover&img=1&zoom=5&sig=ACfU3U02K8fpEVzzHWYb7cOmTwT57Sq6IA&source=gbs_gdata"/>
    <link rel="http://schemas.google.com/books/2008/info"
          type="text/html"
          href="http://books.google.com/books?id=8cp-Z_G42g4C&dq=IT+IS+A+TRUTH+universally+acknowledged&ie=ISO-8859-1&source=gbs_gdata"/>
    <link rel="http://schemas.google.com/books/2008/preview"
          type="text/html"
          href="http://books.google.com/books?id=8cp-Z_G42g4C&pg=PR7&dq=IT+IS+A+TRUTH+universally+acknowledged&ie=ISO-8859-1&sig=ACfU3U3vfnNozPFp0krr9m0q8VWLnDvjPA&source=gbs_gdata"/>
    <link rel="http://schemas.google.com/books/2008/annotation"
          type="application/atom+xml"
          href="http://books.google.com/books/feeds/users/me/volumes"/>
    <link rel="alternate"
          type="text/html"
          href="http://books.google.com/books?id=8cp-Z_G42g4C&dq=IT+IS+A+TRUTH+universally+acknowledged&ie=ISO-8859-1"/>
    <link rel="self"
          type="application/atom+xml"
          href="http://www.google.com/books/feeds/volumes/8cp-Z_G42g4C"/>
    <gbs:embeddability value="http://schemas.google.com/books/2008#embeddable"/>
    <gbs:viewability value="http://schemas.google.com/books/2008#view_partial"/>
    <dc:creator>Jane Austen</dc:creator>
    <dc:creator>James Kinsley</dc:creator>
    <dc:creator>Fiona Stafford</dc:creator>
    <dc:date>2004</dc:date>
    <dc:description>
      If a truth universally acknowledged can shrink quite so rapidly into
      the opinion of a somewhat obsessive comic character, the reader may reasonably feel ...
    </dc:description>
    <dc:format>382</dc:format>
    <dc:identifier>8cp-Z_G42g4C</dc:identifier>
    <dc:identifier>ISBN:0192802380</dc:identifier>
    <dc:publisher>Oxford University Press, USA</dc:publisher>
    <dc:subject>Fiction</dc:subject>
    <dc:title>Pride and Prejudice</dc:title>
    <dc:title>A Novel</dc:title>
  </entry>
</feed>

For information about what each of these elements means, see the Data API feed elements reference guide, the Google Data APIs Protocol Reference document, or the Atom 1.0 specification.

If your request fails for some reason, the Data API may return a different status code. More information about HTTP status codes is available in the Google Data APIs Protocol Reference document.

Partner Co-Branded Search

Google Books provides Co-Branded Search, which lets content partners provide full-text search of their books from their own websites.

If you are a partner who wants to do Co-Branded Search using the Data API, you may do so by modifying the feed URL above to point to your Co-Branded Search implementation. If, for example, a Co-Branded Search is available at the following URL:

http://books.google.com/books/p/PARTNER_COBRAND_ID?q=football

then you can obtain the same results using the Data API at the following URL:

http://books.google.com/books/feeds/p/PARTNER_COBRAND_ID/volumes?q=football+-soccer

For additional information or support, visit our Partner help center.

Using community features

Adding a rating

A user can add a rating to a book. Google Books uses a 1-5 rating system in which 1 is the lowest rating. Users cannot update or delete ratings.

Each entry returned in a Data API feed includes two elements that contain information relevant to user ratings:

  • The <gd:rating> element identifies the rating scale (minimum and maximum possible ratings), the number of ratings the book has received from users, and the average of those ratings. This element is returned only if the book has been rated. The XML excerpt below shows an example of this element in an entry:

    <feed>
  <entry>
    ...
    <gd:rating min='1' max='5' average='4.24'/>
  </entry>
</feed>

  • A <link> element identifies the URL to which you post a request to add a rating to a book. Each entry includes several <link> elements; the relevant one for ratings is the one for which the rel attribute value is http://schemas.google.com/books/2008/annotation. The XML excerpt below shows an example of this element in an entry:

    <feed>
  <entry>
    <link rel="http://schemas.google.com/books/2008/annotation"
      type="application/atom+xml"
      href="http://books.google.com/books/feeds/users/me/volumes"/>
    ...
  </entry>
</feed>

To add a rating, send an authenticated HTTP POST request that identifies the book being rated and gives the rating. (The authentication token identifies the user who is rating the volume.)

The following XML is an example of how to add a rating to a book. Note that the value attribute of the <gd:rating> element must be an integer from 1 to 5, inclusive, or 0 to clear an existing rating.

POST /books/feeds/users/me/volumes
Host: books.google.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: AuthSub token="AUTHORIZATION_TOKEN"

<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom"
       xmlns:gd="http://schemas.google.com/g/2005">
  <id>http://www.google.com/books/feeds/volumes/VOLUME_ID<id>
  <gd:rating value="4"/>
</entry>

If the Data API successfully adds the rating, it returns an HTTP 201 Created response code.

If your HTTP request specifies an invalid value for the <gd:rating> element's value attribute, a value other than 1 for the min attribute, or a value other than 5 for the max attribute, then the Data API returns an error.

Reviews

In addition to ratings, authenticated users can submit reviews or edit their reviews. For information on how to request previously submitted reviews, see Retrieving annotations.

Adding a review

To add a review, send an HTTP POST request to the URL identified in the <link> element for which the rel attribute value is http://schemas.google.com/books/2008/annotation. The actual review that you are submitting appears as the value of the <gbs:review> element in the XML that constitutes the body of the POST request.

The following example demonstrates how to add a review to a book.

POST /books/feeds/users/me/volumes
Host: books.google.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: AuthSub token="AUTHORIZATION_TOKEN"

<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom"
    xmlns:gbs="http://schemas.google.com/books/2008">
  <id>http://www.google.com/books/feeds/volumes/VOLUME_ID<id>
  ...
  <gbs:review>This book is all you ever wanted.</gbs:review>
</entry>

Editing a review

To update an existing review, first you retrieve the review you want to update, then you modify it, and then you send a PUT request, with the updated review in the message body, to the review's edit URL. Use the application/atom+xml content type. Be sure that the <id> value in the entry you PUT exactly matches the <id> of the existing entry.

The edit URL is highlighted in the following entry:

<entry>
  <link rel="edit" type="application/atom+xml"
      href="http://www.google.com/books/feeds/users/USER_ID/volumes/VOLUME_ID"/>
  ...
</entry>

The following example demonstrates how to modify a review.

POST /books/feeds/users/me/volumes/VOLUME_ID
Host: books.google.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: AuthSub token="AUTHORIZATION_TOKEN"

<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom"
    xmlns:gbs="http://schemas.google.com/books/2008">
  ...
  <gbs:review>I could not even understand the first word!</gbs:review>
</entry>

IMPORTANT: To ensure forward compatibility, be sure that when you PUT an updated entry, you preserve all the XML that was present when you retrieved the entry from Data API. Otherwise, when we implement new stuff and include <new-awesome-feature> elements in the feed, your client won't return them and your users will miss out. The Google Data API client libraries all handle this correctly, so if you're using one of the libraries you're all set.

Troubleshooting Tip: Some firewalls block HTTP PUT messages. To get around this, you can include a X-HTTP-Method-Override: PUT header in a POST request. For details, see the Google Data API protocol basics document.

Labels

You can use the Data API to label volumes with keywords. A user can submit, retrieve and modify labels. See Retrieving annotations for how to read previously submitted labels.

Submitting a set of labels

To submit labels, send an HTTP POST request to the URL identified in the <link> element for which the scheme attribute value is http://schemas.google.com/books/2008/annotation.

Specify each label you're submitting as a <category> element with a scheme value of http://schemas.google.com/books/2008/labels.

The following example demonstrates how to add labels to a book.

POST /books/feeds/users/me/volumes
Host: books.google.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: AuthSub token="AUTHORIZATION_TOKEN"

<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom"
    xmlns:gbs="http://schemas.google.com/books/2008">
  <id>http://www.google.com/books/feeds/volumes/VOLUME_ID<id>
  <category scheme="http://schemas.google.com/books/2008/labels" term="fiction"/>
  <category scheme="http://schemas.google.com/books/2008/labels" term="soporific"/>
</entry>

Editing labels

To update existing labels, first you retrieve the labels you want to update, then you modify them, and then you send a PUT request, with the updated labels in the message body, to the book's edit URL. Use the application/atom+xml content type. Be sure that the <id> value in the entry you PUT exactly matches the <id> of the existing entry for that book.

The edit URL is highlighted in the following entry:

<entry>
  <link rel="edit" type="application/atom+xml"
      href="http://www.google.com/books/feeds/users/USER_ID/volumes/VOLUME_ID"/>
  ...
</entry>

The following example demonstrates how to modify a label for a book.

PUT /books/feeds/users/me/volumes/VOLUME_ID
Host: books.google.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: AuthSub token="AUTHORIZATION_TOKEN"

<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom"
    xmlns:gbs="http://schemas.google.com/books/2008">
  <category scheme="http://schemas.google.com/books/2008/labels" term="bestseller"/>
  ...
</entry>

This removes the previous labels and replaces them with the single label bestseller.

To modify one of the existing labels while leaving the others intact, include the unmodified labels in the entry that you PUT.

IMPORTANT: To ensure forward compatibility, be sure that when you PUT an updated entry, you preserve all the XML that was present when you retrieved the entry from Data API. Otherwise, when we implement new stuff and include <new-awesome-feature> elements in the feed, your client won't return them and your users will miss out. The Google Data API client libraries all handle this correctly, so if you're using one of the libraries you're all set.

Troubleshooting Tip: Some firewalls block HTTP PUT messages. To get around this, you can include a X-HTTP-Method-Override: PUT header in a POST request. For details, see the Google Data API protocol basics document.

Retrieving annotations: reviews, ratings, and labels

You can use the Data API to retrieve annotations submitted by a given user. Annotations include reviews, ratings, and labels. To retrieve any user's annotations, you can send an unauthenticated GET that includes the user's user ID. To retrieve the authenticated user's annotations, use the value me as the user ID.

GET http://www.google.com/books/feeds/users/USER_ID/volumes

The Data API then returns an HTTP 200 OK status code and a standard Atom 1.0 feed containing all the books annotated by the specified user.

To request annotations for a particular volume, append the volume ID:

GET http://www.google.com/books/feeds/users/USER_ID/volumes/VOLUME_ID

Book collections and My Library

Google Books provides a number of user-specific book collections, each of which has its own feed.

The most important collection is the user's My Library, which represents the books the user would like to remember, organize, and share with others. This is the collection the user sees when accessing his or her My Library page.

Retrieving books in a user's library

The following sections describe how to retrieve a list of books from a user's library, with or without query parameters.

You can query a Data API public feed without authentication.

Retrieving all books in a user's library

To retrieve the user's books, send an HTTP GET request to the My Library feed URL. The Data API then returns a feed containing the appropriate library entries. For example, to get a list of books for a given user, send the following HTTP request to the Data API (with the appropriate value in place of USER_ID). To get the library of the authenticated user, use me in place of USER_ID.

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

The Data API then returns an HTTP 200 OK status code and a standard Atom 1.0 feed containing the books. Annotations by the user (rating, review, and labels) are visible in the feed. For more information, see Using community features.

Note: The feed may not contain all of the user's books, because there's a default limit on the number of results returned. For more information, see the max-results query parameter in Searching for books.

The following is an example of a books feed for a library with only one entry.

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom"
         xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"
         xmlns:gbs="http://schemas.google.com/books/2008"
         xmlns:dc="http://purl.org/dc/terms"
         xmlns:gd="http://schemas.google.com/g/2005">
  <id>http://books.google.com/books/feeds/users/12976283306927349769/collections/library/volumes</id>
  <updated>2008-08-22T00:03:57.000Z</updated>
  <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/books/2008#volume"/>
  <title type="text">Collection 0</title>
  <link rel="alternate"
           type="text/html"
           href="http://books.google.com/books?uid=12976283306927349769&ie=ISO-8859-1"/>
  <link rel="http://schemas.google.com/g/2005#feed"
           type="application/atom+xml"
           href="http://books.google.com/books/feeds/users/12976283306927349769/collections/library/volumes"/>
  <link rel="http://schemas.google.com/g/2005#post"
           type="application/atom+xml"
           href="http://books.google.com/books/feeds/users/12976283306927349769/collections/library/volumes"/>
  <link rel="self"
           type="application/atom+xml"
           href="http://books.google.com/books/feeds/users/12976283306927349769/collections/library/volumes?max-results=1"/>
  <link rel="next"
           type="application/atom+xml"
           href="http://books.google.com/books/feeds/users/12976283306927349769/collections/library/volumes?start-index=2&max-results=1"/>
  <author>
    <name>Willy</name>
  </author>
  <generator version="beta">Data API</generator>
  <openSearch:totalResults>2</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>1</openSearch:itemsPerPage>
  <entry>
    <id>http://books.google.com/books/feeds/users/12976283306927349769/collections/library/volumes/Mfer_MFwQrkC</id>
    <updated>2008-08-22T00:03:57.000Z</updated>
    <category scheme="http://schemas.google.com/g/2005#kind"
                 term="http://schemas.google.com/books/2008#volume"/>
    <title type="text">Hamlet</title>
    <link rel="http://schemas.google.com/books/2008/thumbnail"
             type="image/jpeg"
             href="http://bks2.books.google.com/books?id=Mfer_MFwQrkC&printsec=frontcover&img=1&zoom=5&sig=ACfU3U1o90VpMryPI7WKSyIhmAWdC1uDtw&source=gbs_gdata"/>
    <link rel="http://schemas.google.com/books/2008/info"
             type="text/html"
             href="http://books.google.com/books?id=Mfer_MFwQrkC&ie=ISO-8859-1&source=gbs_gdata"/>
    <link rel="http://schemas.google.com/books/2008/preview"
             type="text/html"
             href="http://books.google.com/books?id=Mfer_MFwQrkC&printsec=frontcover&ie=ISO-8859-1&sig=ACfU3U0MMne1ckXkvgCzyFlkXFe_wL7mag&source=gbs_gdata"/>
    <link rel="http://schemas.google.com/books/2008/annotation"
             type="application/atom+xml"
             href="http://books.google.com/books/feeds/users/me/volumes"/>
    <link rel="alternate"
             type="text/html"
             href="http://books.google.com/books?id=Mfer_MFwQrkC&ie=ISO-8859-1"/>
    <link rel="self"
             type="application/atom+xml"
             href="http://books.google.com/books/feeds/users/12976283306927349769/collections/library/volumes/Mfer_MFwQrkC"/>
    <link rel="edit"
             type="application/atom+xml"
             href="http://books.google.com/books/feeds/users/12976283306927349769/collections/library/volumes/Mfer_MFwQrkC"/>
    <author>
      <name>12976283306927349769</name>
    </author>
    <gbs:embeddability value="http://schemas.google.com/books/2008#embeddable"/>
    <gd:rating min="1" max="5" average="4.00"/>
    <gbs:review type="text">I don&#39;t like this book that much... really...</gbs:review>
    <gbs:viewability value="http://schemas.google.com/books/2008#view_partial"/>
    <dc:creator>William Shakespeare</dc:creator>
    <dc:creator>Roma Gill</dc:creator>
    <dc:date>2002.02</dc:date>
    <dc:description>Designed specifically for students unfamiliar with Shakespeare&#39;s rich literary legacy, these new editions present Shakespeare&#39;s sometimes-intimidating Middle English in a way thatis easy-to-read and engaging for ages twelve and up.</dc:description>
    <dc:format>178</dc:format>
    <dc:identifier>Mfer_MFwQrkC</dc:identifier>
    <dc:identifier>ISBN:0198320493</dc:identifier>
    <dc:publisher>Oxford University Press, USA</dc:publisher>
    <dc:subject>Juvenile Nonfiction</dc:subject>
    <dc:title>Hamlet</dc:title>
  </entry>
</feed>

Searching for books in a user's library

Just as you can search across all books, you can do a full-text search over just the books in a user's library. To do this, just append the appropriate query parameters to the user's volume feed.

For example, the following URL returns all the books in your library that contain the word "bear":

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

For a list of the supported query parameters, see the query parameters section. In addition, you can search for books that have been labeled by the user:

http://books.google.com/books/feeds/users/USER_ID/collections/library/volumes/-/label

or

http://books.google.com/books/feeds/users/USER_ID/collections/library/volumes?category=label

Updating books in a user's library

You can use the Data API to add a book to, or remove a book from, a user's library. Ratings, reviews, and labels are valid across all the collections of a user, and are thus edited using the annotation feed (see Using community features).

Adding a book to a library

After authenticating, you can add books to the current user's library.

First, create an XML representation of the book to add. This XML needs to be in the form of an Atom <entry> element, which might look like this:

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'>
  <id>http://books.google.com/books/feeds/volumes/VOLUME_ID</id>
</atom:entry>

To publish this entry, send it to the user library's post URL as follows. First, place your Atom <entry> element in the body of a new POST request, using the application/atom+xml content type. Then find the books's post URL by locating the <link> element where the rel attribute ends with #post. The user library's post URL is given as the href attribute of this element, which is in this format:

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

The user ID must be the ID of the authenticated user, or else the keyword me.

The Data API adds the book using the entry you sent, then returns an HTTP 201 CREATED status code, along with a copy of the new book in the form of an <entry> element. The entry returned is the same one you sent, but it also contains various elements added by the Data API, such as an <id> element.

If your request fails for some reason, the Data API may return a different status code. For information about the status codes, see the Google Data API protocol reference document.

Removing a book from a library

To remove a book from a user's library, send an HTTP DELETE request to the book's edit URL. This is the URL specified in the entry's edit link, the link for which the rel value ends in #edit.

Troubleshooting Tip: Some firewalls block HTTP DELETE messages. To get around this, you can include a X-HTTP-Method-Override: DELETE header in a POST request. For details, see the Google Data API protocol basics document.

Understanding Data API error messages

This section discusses the response that may accompany a failed Data API request. For more information about the possible HTTP response codes, see the reference guide.

When a Data API request fails, the Data API returns an HTTP 4xx or 5xx response code that generically identifies the failure as well as a plain text response that provides more specific information about the error(s) that caused the failure. The types of error you might encounter fall into a few categories:

  • Internal server error: typically a transient problem with our servers; please retry later. You can report issues to our API group and check for status updates on significant outages using our downtime notification group.
  • Unsupported ... request: look for a typo in the request or the XML entry that you submitted to the service.
  • The request exceeds the API quota on ... queries: you have reached your quota for that type of query for the time being; please retry in a few hours. If you believe the quota we set is too low for your application, please contact us.