This document provides detailed reference documentation for the raw protocol (XML and HTTP) for the Google Book Search Data API.
This document doesn't contain information about the programming-language client libraries. For client-library reference information, see the links from the programming-language-specific sections of the developer's guide.
This document is intended for programmers who want to write client applications that can interact with Book Search.
It's a reference document; it assumes that you understand the concepts presented in the developer's guide, and the general ideas behind the Google Data APIs protocol.
Book Search provides a variety of representations of book-related data. This section describes the basic feed types and their URLs, all of which return one or more book results: the search feed, the Co-Branded Search feed, the single-item feed, the user library feed, and the user annotation feed.
The search feed is a public read-only feed returned in response to a request to search for books. To retrieve search results, send a Data API request to the following URL:
http://books.google.com/books/feeds/volumes
Search requests can use any of the query paramaters defined in the query parameters reference section of this document. For example, the following URL requests all books related to the query "Elizabeth Bennet," starting with the 21st search and returning 10 results:
http://books.google.com/books/feeds/volumes? q=Elizabeth+Bennet &start-index=21 &max-results=10
Additional information is available in the searching for books section of the developer's guide.
Content partners using Co-Branded Search can access a search result feed restricted to just their volumes by including the Co-Branded instance name in the feed URL:
http://books.google.com/books/feeds/p/PARTNER_COBRAND_ID/volumes?q=football+-soccer
For more information, see the Co-Branded Search section of the developer's guide.
As is standard with the Google Data APIs, it is possible to obtain information about a single volume using the single-item feed. The URL is:
http://www.google.com/books/feeds/volumes/VOLUME_ID
Here, VOLUME_ID represents the unique string Book Search has assigned to this volume (such as s1gVAAAAYAAJ). A link to the individual volume feed is provided via the <id> child of each entry in the other volume feeds. For more information on how feeds are related, see Navigating between feeds and resources.
The user library feed is a read/write feed representing a list of books that a particular user has explicitly added to their My Library collection. On the Book Search website, a user can view and edit their library, and this list is also publicly visible to other Book Search users.
To request a feed of the authenticated user's library collection, send an HTTP GET request to the following URL. Note: For this request, you must provide an authentication token in the Authorization HTTP request header. The authentication token enables Book Search to identify the user.
http://books.google.com/books/feeds/users/me/collections/library/volumes
To request a feed of another user's library, send an HTTP GET request to the following URL. Note that this request does not require authentication.
http://books.google.com/books/feeds/users/USER_ID/collections/library/volumes
In the URL above, replace USER_ID with the user's Book Search user identifier string (which appears, for example, as the uid parameter of that user's My Library page URL).
For more information on querying within a user's library, see the user library search section of the developer's guide.
The user annotation feed is a read/write feed of a particular user's reviews, ratings, and labels for books. This content is presented in a number of ways on the Book Search site (such as on the About This Book page), and also as elements in the user's library feed.
To request a feed of the authenticated user's library annotations, send an HTTP GET request to the following URL. Note: For this request, you must provide an authentication token in the Authorization HTTP request header. The authentication token enables Book Search to identify the user.
http://books.google.com/books/feeds/users/me/volumes
To request a feed of another user's annotations, send an HTTP GET request to the following URL. Note that this request does not require authentication.
http://books.google.com/books/feeds/users/USER_ID/volumes
In the URL above, replace USER_ID with the user's Book Search user identifier string (which appears, for example, as the uid parameter of that user's My Library page URL).
Every feed and entry contains <link rel="relationshipID"> elements that specify links to related feeds, entries, or resources. These elements enable you to obtain feed and resource URLs dynamically, without hardcoding the URLs into your application.
For example, the following <link> element, which
might appear in a book entry, provides a link to a feed that contains
a user's own ratings and reviews:
<link rel="http://schemas.google.com/books/2008/annotation" type="application/atom+xml" href="http://books.google.com/books/feeds/users/me/volumes"/>
Similarly, you can get a cover image for a book result using the URL provided by the thumbnail <link> element:
<link rel="http://schemas.google.com/books/2008/thumbnail" type="image/jpeg" href="http://bks7.books.google.com/books?id=aFbCdW8CcuAC&printsec=frontcover&img=1&zoom=5&sig=ACfU3U3ijgJlMlb3ztsN-H4Ka7HW7CSHfw&source=gbs_gdata"/>
The use cases in the developer's guide show how to use these elements to navigate from one feed or resource to another. In addition, the following diagram illustrates the interconnections between the various Book Search feeds and pages. Each solid arrow denotes a <link> element to another feed, and each dotted arrow denotes a <link> to an external resource such as a web page or a thumbnail image.
The following table describes some of the common HTTP status codes returned by the Book Search Data API. For additional response codes, see the relevant section of the Google Data APIs protocol.
| Code | Explanation |
|---|---|
| 200 OK | No error. The request to retrieve or update the resource, feed, or entity was successful. |
| 201 CREATED | Creation of a resource was successful. |
| 400 BAD REQUEST | Invalid request URI or header, or unsupported nonstandard parameter. |
| 401 UNAUTHORIZED | Authorization required. This may occur when a request did not contain an Authorization header, when the format of the Authorization header was invalid, or that the authentication token supplied in the header was invalid. See the Authentication section of the developer's guide. |
| 403 FORBIDDEN | Unsupported standard parameter, quota exceeded, or authentication or authorization failed. |
| 404 NOT FOUND | Resource (such as a feed or entry) not found. |
| 500 INTERNAL SERVER ERROR | Internal error. This is the default code that is used for all unrecognized errors. |
When a Data API request fails, Book Search 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:
The Book Search Data API supports the following standard Google Data API query parameters:
| Name | Support |
|---|---|
q |
Search feed, Co-Branded Search feed, User library feed, User annotation feed |
start-index |
Search feed, Co-Branded Search feed, User library feed, User annotation feed |
max-results |
Search feed, Co-Branded Search feed, User library feed, User annotation feed |
start-index |
Search feed, Co-Branded Search feed, User library feed, User annotation feed |
/-/category |
User library feed |
category |
User library feed |
alt |
Search feed, Co-Branded Search feed, User library feed, User annotation feed |
For more information on querying the Book Search Data API, see the searching for books and user library search sections of the developer's guide.
Book Search does not support the updated-min, updated-max, published-min, or published-max parameters.
In addition to the standard Google Data API query parameters, the Book Search Data API supports the following parameters:
| Name | Description | Notes |
|---|---|---|
min-viewability |
Viewability filter |
|
In addition to the standard Data API elements, the Book Search Data API uses the following elements.
For information about the standard Google Data API elements, see the Atom specification and the Kinds document.
As a Google Data API, the Book Search Data API uses a number of elements defined by the Atom Publishing Protocol. These elements are in the atom namespace, which is the default namespace for elements described in this document.
Although these elements are documented in the general Google Data APIs Protocol Reference, the sections that follow provide further details about elements that have values or semantics specific to Book Search.
The <category> element provides some classification for the current entry.
<category> element appears as a child of either <feed> or <entry>, it can identify the type of item described in each entry. The value of the scheme attribute is http://schemas.google.com/g/2005#kind and the value of the term attribute indicates whether the entries describe book volumes, thumbnail images, reviews, and so on.<category> element also appears as a child of <entry> to specify any labels provided by the user for a particular book. In this case, the scheme attribute is http://schemas.google.com/books/2008/labels, indicating that the term attribute value is a user-provided label.For more information on how various feeds and resources are linked, see the Navigating between feeds and resources section of this document.
| Property | Type | Description |
|---|---|---|
@scheme |
xsd:string |
The
|
@term |
xsd:string |
The term identifies the type of entity contained in an entry, or else a user-entered label associated with a book. |
<category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/books/2008#volume"/> <category scheme="http://schemas.google.com/books/2008/labels" term="ForLydia"/>
namespace atom = "http://www.w3.org/2005/Atom"
start = books_booksCategory
books_booksCategory =
element atom:category {
attribute label { xsd:string }?,
attribute scheme {
"http://schemas.google.com/books/2008/labels" |
"http://schemas.google.com/g/2005#kind" },
attribute term { xsd:string }
}
The <link> element contains an IRI reference that's relevant to a feed or an entry. Example references pointed to by this element include reviews, thumbnail images, preview URLs, and adjacent search result pages. These elements enable you to obtain feed and resource URLs dynamically, without hardcoding the URLs into your application. For more information, see the Navigating between feeds and resources section of this document.
This element appears as a child of <feed> and <entry>. There may be multiple <link> children per element.
| Property | Type | Description |
|---|---|---|
@rel |
xsd:string |
The
The |
@type |
xsd:string |
The type attribute specifies the media type of the resource at the associated URL. The links in a Book Search Data API response typically refer to an HTML page, an image, or another Data API response (Atom feed). Thus, the most common values for the type attribute are text/html, image/jpeg, and application/atom+xml. |
@href |
xsd:string |
The href attribute specifies a URI that identifies the resource identified in the <link> element. |
<link rel="http://schemas.google.com/books/2008/thumbnail" type="image/jpeg" href="http://bks3.books.google.com/books?id=o9dyGQAACAAJ&printsec=frontcover&img=1&zoom=5&sig=ACfU3U2sYY4y7XFmHKMYvISqfVGKwdN93w&source=gbs_gdata"/> <link rel="http://schemas.google.com/books/2008/info" type="text/html" href="http://books.google.com/books?id=o9dyGQAACAAJ&dq=pride+and+prejudice&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=o9dyGQAACAAJ&dq=pride+and+prejudice&ie=ISO-8859-1&source=gbs_gdata"/> <link rel="alternate" type="text/html" href="http://books.google.com/books?id=o9dyGQAACAAJ&dq=pride+and+prejudice&ie=ISO-8859-1"/> <link rel="self" type="application/atom+xml" href="http://www.google.com/books/feeds/volumes/o9dyGQAACAAJ"/>
namespace atom = "http://www.w3.org/2005/Atom"
start = books_booksLink
books_booksLink =
element atom:link {
attribute href { xsd:string },
attribute rel {
"edit" |
"http://schemas.google.com/books/2008/info" |
"http://schemas.google.com/books/2008/preview" |
"http://schemas.google.com/books/2008/thumbnail" |
"http://schemas.google.com/books/2008/annotation" |
"http://schemas.google.com/g/2005#batch" |
"http://schemas.google.com/g/2005#post" |
"next" |
"previous" |
"self" },
attribute title { xsd:string }?,
attribute type {
"application/atom+xml" |
"image/jpeg" |
"image/png" |
"text/html" }
}
Book Search uses OpenSearch elements to augment the feed with the information necessary to render paginated search results. The schema URL for the openSearch namespace is http://a9.com/-/spec/opensearchrss/1.0.
Book Search uses the standard OpenSearch elements in the standard way, so for reference information about those elements, see the OpenSearch specification.
The Book Search Data API uses the Dublin Core Metadata Element Set under the dc namespace to provide standard information about each book entry. The Dublin Core Metadata Element Set is a vocabulary of fifteen properties for use in describing resources such as books. The schema URL for the dc namespace is http://purl.org/dc/elements/1.1/.
The <dc:creator> element identifies an author—or more generally, an entity responsible for creating the volume in question. Examples of a creator include a person, an organization, or a service. In the case of anthologies, proceedings, or other edited works, this field may be used to indicate editors or other entities responsible for collecting the volume's contents.
This element appears as a child of <entry>. If there are multiple authors or contributors to the book, there may be multiple <dc:creator> elements in the volume entry (one for each creator or contributor).
| Property | Type | Description |
|---|---|---|
text() |
xsd:string |
The name of an author, creator, or contributor to this book. |
<dc:creator>Jane Austen</dc:creator>
namespace dc = "http://purl.org/dc/terms"
start = dublincore_creator
dublincore_creator =
element dc:creator {
xsd:string
}
The <dc:date> element indicates the publication date of the specific volume in question. If the book is a reprint, this is the reprint date, not the original publication date. The date is encoded according to the ISO-8601 standard (and more specifically, the W3CDTF profile).
The <dc:date> element can appear only as a child of <entry>.
| Property | Type | Description |
|---|---|---|
text() |
xsd:string |
An ISO-8601-formatted publication date. |
<dc:date>1813-01-28</dc:date>
namespace dc = "http://purl.org/dc/terms"
start = dublincore_date
dublincore_date =
element dc:date {
xsd:string
}
The <dc:description> element includes text that describes a book or book result. In a search result feed, this may be a search result "snippet" that contains the words around the user's search term. For a single volume feed, this element may contain a synopsis of the book.
The <dc:description> element can appear only as a child of <entry>.
| Property | Type | Description |
|---|---|---|
text() |
xsd:string |
The description of the volume. |
<dc:description>Austen's comedy of manners--one of the most popular novels of all time--features splendidly civilized sparring between the proud Mr...</dc:description>
namespace dc = "http://purl.org/dc/terms"
start = dublincore_description
dublincore_description =
element dc:description {
xsd:string
}
The <dc:format> element describes the physical properties of the volume. Currently, it indicates the number of pages in the book, but more information may be added to this field in the future.
This element can appear only as a child of <entry>.
| Property | Type | Description |
|---|---|---|
text() |
xsd:string |
A string describing physical properties of this book. |
<dc:format>95 pages</dc:format>
namespace dc = "http://purl.org/dc/terms"
start = dublincore_format
dublincore_format =
element dc:format {
xsd:string
}
The <dc:identifier> element provides an unambiguous reference to a particular book.
<entry> contains at least one <dc:identifier> child.s1gVAAAAYAAJ). This is the ID that appears in the book's URL in the Book Search GUI, as well as in the URL of that book's single item feed.<dc:identifier> elements. These provide alternate, external identifiers to the volume. Such identifiers may include the ISBNs, ISSNs, Library of Congress Control Numbers (LCCNs), and OCLC numbers; they are prepended with a corresponding namespace prefix (such as "ISBN:").<dc:identifier> can be passed to the Dynamic Links, used to instantiate an Embedded Viewer, or even used to construct static links to Book Search.The <dc:identifier> element can appear only as a child of <entry>.
| Property | Type | Description |
|---|---|---|
text() |
xsd:string |
A unique identifier string for this volume. |
<dc:identifier>qCkfAAAACAAJ</dc:identifier> <dc:identifier>ISBN:0582780934</dc:identifier>
namespace dc = "http://purl.org/dc/terms"
start = dublincore_identifier
dublincore_identifier =
element dc:identifier {
xsd:string
}
The <dc:publisher> element contains the name of the entity responsible for producing and distributing the volume (usually the specific edition of this book). Examples of a publisher include a person, an organization, or a service.
This element can appear only as a child of <entry>. If there is more than one publisher, multiple <dc:publisher> elements may appear.
| Property | Type | Description |
|---|---|---|
text() |
xsd:string |
The name of the publisher. |
<dc:publisher>T. Egerton of the Whitehall Military Library</dc:publisher>
namespace dc = "http://purl.org/dc/terms"
start = dublincore_publisher
dublincore_publisher =
element dc:publisher {
xsd:string
}
The <dc:subject> element identifies the topic of the book. Usually this is a Library of Congress Subject Heading (LCSH) or Book Industry Standards and Communications Subject Heading (BISAC).
The <dc:subject> element can appear only as a child of <entry>. There may be multiple <dc:subject> elements per entry.
| Property | Type | Description |
|---|---|---|
text() |
xsd:string |
A subject for this book according to some classification scheme. |
<dc:subject>Fiction</dc:subject>
namespace dc = "http://purl.org/dc/terms"
start = dublincore_subject
dublincore_subject =
element dc:subject {
xsd:string
}
The <dc:title> element contains the title of a book as it was published. If a book has a subtitle, it appears as a second <dc:title> element in the book result's <entry>.
| Property | Type | Description |
|---|---|---|
text() |
xsd:string |
A title or subtitle of a volume. |
<dc:title>Pride and Prejudice</dc:title> <dc:title>A Novel</dc:title>
namespace dc = "http://purl.org/dc/terms"
start = dublincore_title
dublincore_title =
element dc:title {
xsd:string
}
Book Search provides a custom element namespace, gbs, for use in the various volume and reviews feeds. The schema URL for the gbs namespace is http://schemas.google.com/books/2008.
Google Book Search respects the user's local copyright restrictions. As a result, previews or full views of some books are not available in all locations. The <gbs:viewability> element indicates whether a book is fully viewable, can be previewed, or only has "about the book" information. These three "viewability modes" are the same ones returned by the Dynamic Links API.
Note: The viewability mode for a given book varies according to the end user's location. To ensure your users get accurate and consistent results, we recommend that you include the end-user IP address in every query to the Book Search Data API. For more information, see the Setting user location section in the developer's guide.
The <gbs:viewability> element can appear only as a child of <entry>.
| Property | Type | Description |
|---|---|---|
@value? |
xsd:string |
A programmatic value representing the book's "viewability" mode.
|
<gbs:viewability value="http://schemas.google.com/books/2008#view_all_pages"/>
namespace gbs = "http://schemas.google.com/books/2008"
start = books_viewability
books_viewability =
element gbs:viewability {
attribute value { xsd:string }?
}
Many of the books found on Google Book Search can be embedded on third-party sites using the Embedded Viewer. The <gbs:embeddability> element indicates whether a particular book result is available for embedding. By definition, a book that cannot be previewed on Book Search cannot be embedded on third-party sites.
Note: Some books cannot be accessed by users in certain countries. To ensure you only embed books that are available to your end users, we recommend that you include the end-user IP address in every query to the Book Search Data API. For more information, see the Setting user location section in the developer's guide.
The <gbs:embeddability> element can appear only as a child of <entry>.
| Property | Type | Description |
|---|---|---|
@value? |
xsd:string |
A programmatic value representing the book's embeddability.
|
<gbs:embeddability value="http://schemas.google.com/books/2008#embeddable"/>
namespace gbs = "http://schemas.google.com/books/2008"
start = books_embeddability
books_embeddability =
element gbs:embeddability {
attribute value { xsd:string }?
}
When present, the <gbs:review> element contains a user-generated review for a given book. This element currently appears only in the user library and user annotation feeds, as a child of <entry>.
| Property | Type | Description |
|---|---|---|
text() |
xsd:string |
Text content of the review. |
@type? |
xsd:string |
Type of text construct (typically text, html, or xhtml). |
@xml:lang? |
xsd:string |
Automatically-identified language of the review. May be incorrect. |
<gbs:review type="text" xml:lang="en">A great beach read!</gbs:review>
namespace gbs = "http://schemas.google.com/books/2008"
namespace xml = "http://www.w3.org/XML/1998/namespace"
start = books_review
books_review =
element gbs:review {
attribute type { xsd:string }?,
attribute xml:lang { xsd:string }?,
xsd:string
}
You may find the following documents useful: