The Google Book Search Data API allows client applications to view and update Book Search content in the form of Google Data API feeds.
Your client application can use the Book Search 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 Book Search Data API, this document provides examples for interacting with the API using the PHP Client Library. You can download the client library as a standalone release (distributed by Zend) or as part of the Zend Framework. If you need help setting up the PHP client library, the Getting Started Guide is the place to look.
If you're interested in understanding more about the underlying protocol that the library uses, see the Protocol section of this developer's guide.
This document is intended for programmers who want to write applications that can interact with Google Book Search using the PHP client library.
This document assumes that you understand the general ideas behind the Google Data APIs protocol, and that you're familiar with Google Book Search and its My Library features.
For reference information about the PHP classes and methods, see the client library's API guide.
For general Book Search Data API reference information, see the Protocol reference guide.
To use the PHP client library, you must be running PHP >= 5.1.4. You also need to be using Zend_Gdata >= 1.7, which is distributed as part of the Zend Framework. See the Getting Started Guide for more information on configuring your environment.
The snippets of sample code below can be copied/pasted into your code and
modified to fit your needs. There are also two sample applications distributed
with the client library which covers many of the API operations. The
code is located in the /demos/MyLibrary and
/demos/BooksBrowser folders.
Before you can perform any operations with the Book Search Data API, you must initialize a
Zend_Gdata_Books
object, as shown below. Please note that all actions aside from
retrieving public content will require authentication.
|
<?php
require_once 'Zend/Loader.php'; // the Zend dir must be in your include_path
Zend_Loader::loadClass('Zend_Gdata_Books');
$books = new Zend_Gdata_Books();
For authenticated functionality you will also need to include the one of the following helper classes, pending on whether you plan to use ClientLogin or AuthSub (see the authentication section below for more detail).
Zend_Loader::loadClass('Zend_Gdata_AuthSub');
Zend_Loader::loadClass('Zend_Gdata_ClientLogin');
Most of the method examples in this guide operate upon an instance of
Zend_Gdata_Books.
Note: The contents of the Zend library directory must be in your PHP include_path.
For testing purposes, you may want to create a Book Search library. Book Search uses Google Accounts, so if you already have a Google account, you can use the My Library features with that account.
You can access both public and private feeds using the Book Search 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 have an authenticated BooksService object.
AuthSub proxy authentication is used by web applications which need to authenticate their users to Google accounts. The operator does not need access to the username and password for the Book Search user — only special AuthSub tokens are required.
When the user first visits your application, they have not yet been authenticated with Google's services. In this case, you need to provide them with a link directing the user to Google to authenticate your request for access to their Google account. The Zend Framework PHP Google Data client library provides a function to generate this URL. The code below sets up a link to the AuthSubRequest page.
// start a new session
session_start();
function getAuthSubRequestUrl()
{
$next = 'http://www.example.com/welcome.php';
$scope = 'http://www.google.com/books/feeds';
$secure = false;
$session = true;
return Zend_Gdata_AuthSub::getAuthSubTokenUri($next, $scope, $secure, $session);
}
The code above generates a URL which requests a token from Google's
Book Search service. Notice the parameters sent to the getAuthSubRequestUrl
method:
The URL will look something like this:
https://www.google.com/accounts/AuthSubRequest?scope=http%3A%2F%2Fwww.google.com%2Fbooks%2Ffeeds&session=1&secure=0&next=http%3A%2F%2Fwww.example.com%2Fwelcome.php
The user will then follow the link to Google's site and authenticate
to their Google account. Once they return to your application's $next URL, the one-time token will be sent along with the redirect: http://www.example.com/welcome.php?token=DQAADKEDE.
For security, this token is single-use only, so now we need to exchange this single-use token for a session token. The following code snippet shows how to upgrade the token.
$sessionToken = Zend_Gdata_AuthSub::getAuthSubSessionToken($_GET['token']);
In this snippet, the $_GET['token']
variable contains the value from the token query parameter in the
URL. This token value represents a single-use AuthSub token.
Since we specified $session = true in the getAuthSubRequestUrl function above, this token
can be exchanged for an AuthSub session token. as is being done in the code above with the call to getAuthSubSessionToken
The function below performs performs all of these requests. It first checks whether a session token has already been set. If not, it will build an authentication url using the getAuthSubRequestUrl function described earlier. If a single-use token has been found in the URL string ($_GET['token']), it will upgrade it to a session token.
function getAuthSubHttpClient()
{
if (!isset($_SESSION['sessionToken']) && !isset($_GET['token']) ){
echo '<a href="' . getAuthSubRequestUrl() . '">Login!</a>';
return;
} else if (!isset($_SESSION['sessionToken']) && isset($_GET['token'])) {
$_SESSION['sessionToken'] = Zend_Gdata_AuthSub::getAuthSubSessionToken($_GET['token']);
}
$httpClient = Zend_Gdata_AuthSub::getHttpClient($_SESSION['sessionToken']);
return $httpClient;
}
You can then create a fully authenticated Book Search service object by passing in your $httpClient to the constructor of the Zend_Gdata_Books service object, along with your application's identifier and your client ID. The application ID and the client ID identify your application for logging and debugging purposes.
$books = new Zend_Gdata_Books($httpClient, $applicationId, $clientId);
This fully authenticated service object can then be used to perform all further requests with the Book Search Data API. AuthSub session tokens will not expire unless you specifically issue a request to revoke them.
ClientLogin authentication is used in installed applications
that can either store or query your user for their username and
password. To use this form of authentication, call the static
getHttpClient method of the
Zend_Gdata_ClientLogin class, specifying the email
and password of the user, on whose behalf your application is
sending the query. For example:
$username = 'myuser@gmail.com'; $password = 'mypassword'; $service = 'print'; $httpClient = Zend_Gdata_ClientLogin::getHttpClient($username, $password, $service);
Once the credentials have been set, the
$httpClient object can be used to authenticate all
further requests to the Zend_Gdata_Books service object.
$books = new Zend_Gdata_Books($httpClient);
Note: Please refer to the Google Data APIs authentication documentation for more detailed information on both the AuthSub and ClientLogin mechanisms.
The Book Search 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 you create a VolumeQuery object
and pass it to the Books::getVolumeFeed method.
For example, to perform a keyword query, with a filter on
viewability to restrict the results to partial or full view books, use
the setMinViewability and setQuery methods of the VolumeQuery
object. The following code snippet prints the title and viewability of
all volumes whose metadata or text matches the query term "domino":
$books = new Zend_Gdata_Books();
$query = $books->newVolumeQuery();
$query->setQuery('domino');
$query->setMinViewability('partial_view');
$feed = $books->getVolumeFeed($query);
foreach ($feed as $entry) {
echo $entry->getVolumeId();
echo $entry->getTitle();
echo $entry->getViewability();
}
The Query class, and subclasses like
VolumeQuery, are responsible for constructing feed
URLs. The VolumeQuery shown above constructs a URL equivalent to the
following:
http://www.google.com/books/feeds/volumes?q=keyword&min-viewability=partial
Note: Since Book Search results are public, you can issue a Book Search query without authentication.
Here are some of the most common VolumeQuery methods for setting search parameters:
setQuery+) for a space.)q parameter to %22spy+plane%22.
jane+austen+-inauthor:austen returns matches that mention (but are not authored by) Jane Austen.setStartIndexstart-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.
setMaxResults10 and the maximum value is 20.setMinViewability'none' (the default, returning all matching books regardless of viewability), 'partial_view' (returning only books that the user can preview or view in their entirety), or 'full_view' (returning only books that the user can view in their entirety).Note that these search query parameters can also be set for 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.
Google Book Search 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 Book Search 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://www.google.com/books/p/PARTNER_COBRAND_ID?q=football
then you can obtain the same results using the Book Search Data API at the following URL:
http://www.google.com/books/feeds/p/PARTNER_COBRAND_ID/volumes?q=football+-soccer
To specify an alternate URL when querying a volume feed, you can
provide an extra parameter to newVolumeQuery
$query = $books->newVolumeQuery('http://www.google.com/books/p/PARTNER_COBRAND_ID');
For additional information or support, visit our Partner help center.
A user can add a rating to a book. Book Search uses a 1-5 rating system in which 1 is the lowest rating. Users cannot update or delete ratings.
To add a rating, add a Rating object to a VolumeEntry and post it to the annotation feed. In the example below, we start from an empty VolumeEntry object.
$entry = new Zend_Gdata_Books_VolumeEntry(); $entry->setId(new Zend_Gdata_App_Extension_Id(VOLUME_ID)); $entry->setRating(new Zend_Gdata_Extension_Rating(3, 1, 5, 1)); $books->insertVolume($entry, Zend_Gdata_Books::MY_ANNOTATION_FEED_URI);
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.
To add a review, add a Review object to a VolumeEntry and post it to the annotation feed. In the example below, we start from an existing VolumeEntry object.
$annotationUrl = $entry->getAnnotationLink()->href;
$review = new Zend_Gdata_Books_Extension_Review();
$review->setText("This book is amazing!");
$entry->setReview($review);
$books->insertVolume($entry, $annotationUrl);
To update an existing review, first you retrieve the review you want to update, then you modify it, and then you submit it to the annotation feed.
$entryUrl = $entry->getId()->getText();
$review = new Zend_Gdata_Books_Extension_Review();
$review->setText("This book is actually not that good!");
$entry->setReview($review);
$books->updateVolume($entry, $entryUrl);
You can use the Book Search 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.
To submit labels, add a Category object with the scheme LABELS_SCHEME to a VolumeEntry and post it to the annotation feed.
$annotationUrl = $entry->getAnnotationLink()->href;
$category = new Zend_Gdata_App_Extension_Category('rated',
'http://schemas.google.com/books/2008/labels');
$entry->setCategory(array($category));
$books->insertVolume($entry, Zend_Gdata_Books::MY_ANNOTATION_FEED_URI);
You can use the Book Search 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 request that includes the user's user ID. To retrieve
the authenticated user's annotations, use the value me as the user ID.
$feed = $books->getVolumeFeed('http://www.google.com/books/feeds/users/USER_ID/volumes');
(or)
$feed = $books->getUserAnnotationFeed();
// print title(s) and rating value
foreach ($feed as $entry) {
foreach ($entry->getTitles() as $title) {
echo $title;
}
if ($entry->getRating()) {
echo 'Rating: ' . $entry->getRating()->getAverage();
}
}
For a list of the supported query parameters, see the query parameters section.
If you retrieved an annotation entry containing ratings, reviews, and/or labels, you can remove all annotations by calling deleteVolume on that entry.
$books->deleteVolume($entry);
Google Book Search 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.
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 Book Search public feed without authentication.
To retrieve the user's books, send a query to the My Library feed. To get the library of the authenticated user, use me in place of USER_ID.
$feed = $books->getUserLibraryFeed();
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.
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 set the appropriate paramters on the VolumeQuery object.
For example, the following query returns all the books in your library that contain the word "bear":
$query = $books->newVolumeQuery(
'http://www.google.com/books/feeds/users/USER_ID/collections/library/volumes');
$query->setQuery('bear');
$feed = $books->getVolumeFeed($query);
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:
$query = $books->newVolumeQuery(
'http://www.google.com/books/feeds/users/USER_ID/collections/library/volumes');
$query->setCategory(
$query->setCategory('favorites');
$feed = $books->getVolumeFeed($query);
You can use the Book Search 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).
After authenticating, you can add books to the current user's library.
You can either create an entry from scratch if you know the volume ID, or insert an entry read from any feed.
The following example creates a new entry and adds it to the library:
$entry = new Zend_Gdata_Books_VolumeEntry(); $entry->setId(new Zend_Gdata_App_Extension_Id(VOLUME_ID)); $books->insertVolume($entry, Zend_Gdata_Books::MY_LIBRARY_FEED_URI);
The following example adds an existing VolumeEntry object to the library:
$books->insertVolume($entry, Zend_Gdata_Books::MY_LIBRARY_FEED_URI);
To remove a book from a user's library, call deleteVolume on the VolumeEntry object.
$books->deleteVolume($entry);