Using the API

Contents

1. Introduction
   1. Authentication and authorization
   2. Google Books IDs
   3. Setting User Location
2. Working with volumes
   1. Performing a search
   2. Retrieving a specific volume
3. Working with bookshelves
   1. Retrieving a list of a user's public bookshelves
   2. Retrieving a specific public bookshelf
   3. Retrieving a list of volumes on a public bookshelf
4. Working with bookshelves in "My Library"
   1. Retrieving a list of my bookshelves
   2. Retrieving a list of volumes on my bookshelf
   3. Adding a volume to my bookshelf
   4. Removing a volume from my bookshelf
   5. Clearing all volumes from my bookshelf
5. Query parameter reference
   1. Standard query parameters
   2. API-specific query parameters

Introduction

This document is intended for developers who want to write applications that can interact with the Books API. Google Books has a mission to digitize the world's book content and make it more discoverable on the Web. The Books API is a way to search and access that content, as well as to create and view personalization around that content.

If you're unfamiliar with Google Books concepts, you should read Getting Started before starting to code.

Authorizing requests and identifying your application

Every request your application sends to the Books API needs to identify your application to Google. There are two ways to identify your application: using an OAuth 2.0 token (which also authorizes the request) and/or using the application's API key. Here's how to determine which of those options to use:

• If the request requires authorization (such as a request for an individual's private data), then the application must provide an OAuth 2.0 token with the request. The application may also provide the API key, but it doesn't have to.
• If the request doesn't require authorization (such as a request for public data), then the application must provide either the API key or an OAuth 2.0 token, or both—whatever option is most convenient for you.

About authorization protocols

Your application must use OAuth 2.0 to authorize requests. No other authorization protocols are supported. If your application uses Google Sign-In, some aspects of authorization are handled for you.

Authorizing requests with OAuth 2.0

Requests to the Books API for non-public user data must be authorized by an authenticated user.

The details of the authorization process, or "flow," for OAuth 2.0 vary somewhat depending on what kind of application you're writing. The following general process applies to all application types:

1. When you create your application, you register it using the Google Developers Console. Google then provides information you'll need later, such as a client ID and a client secret.
2. Activate the Books API in the Google Developers Console. (If the API isn't listed in the Developers Console, then skip this step.)
3. When your application needs access to user data, it asks Google for a particular scope of access.
4. Google displays a consent screen to the user, asking them to authorize your application to request some of their data.
5. If the user approves, then Google gives your application a short-lived access token.
6. Your application requests user data, attaching the access token to the request.
7. If Google determines that your request and the token are valid, it returns the requested data.

Some flows include additional steps, such as using refresh tokens to acquire new access tokens. For detailed information about flows for various types of applications, see Google's OAuth 2.0 documentation.

Here's the OAuth 2.0 scope information for the Books API:

https://www.googleapis.com/auth/books

To request access using OAuth 2.0, your application needs the scope information, as well as information that Google supplies when you register your application (such as the client ID and the client secret).

Tip: The Google APIs client libraries can handle some of the authorization process for you. They are available for a variety of programming languages; check the page with libraries and samples for more details.

Acquiring and using an API key

Requests to the Books API for public data must be accompanied by an identifier, which can be an API key or an access token.

To acquire an API key:

1. Open the Credentials page.
2. This API supports two types of credentials. Create whichever credentials are appropriate for your project:

   • OAuth: Your application must send an OAuth 2.0 token with any request that accesses private user data. Your application sends a client ID and, possibly, a client secret to obtain a token. You can generate OAuth 2.0 credentials for web applications, service accounts, or installed applications.

     To create an OAuth 2.0 token, click Create new Client ID, provide the required information where requested, and click Create Client ID.

     You can generate OAuth 2.0 credentials for web applications, service accounts, or installed applications.

     Web applications

     A web application is accessed by web browsers over a network.

     • Applications that use JavaScript to access the Books API must specify authorized JavaScript origins. The origins identify the domains from which your application can send API requests.
     • Applications that use languages and frameworks like PHP, Java, Python, Ruby, and .NET must specify authorized redirect URIs. The redirect URIs are the endpoints to which the OAuth 2.0 server can send responses.

     Service accounts

     A service account is used in an application that calls APIs on behalf of an application that does not access user information. This type of application needs to prove its own identity, but it does not need a user to authorize requests. The Google Accounts documentation contains more details about service accounts.

     Installed applications

     An installed application runs on a desktop computer or handheld device. You can create OAuth 2.0 credentials for Android, Chrome, iOS, and other installed applications.

     Android

     You need to specify your Android app's package name and SHA1 fingerprint.

     1. In the Package name field, enter your Android app's package name.
     2. In a terminal, run the Keytool utility to get the SHA1 fingerprint for your digitally signed .apk file's public certificate.

        keytool -exportcert -alias androiddebugkey -keystore path-to-debug-or-production-keystore -list -v

        Note: For the debug.keystore, the password is android. For Eclipse, the debug keystore is typically located at ~/.android/debug.keystore.

        The Keytool prints the fingerprint to the shell. For example:

        $ keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore -list -v
        Enter keystore password: Type "android" if using debug.keystore
        Alias name: androiddebugkey
        Creation date: Aug 27, 2012
        Entry type: PrivateKeyEntry
        Certificate chain length: 1
        Certificate[1]:
        Owner: CN=Android Debug, O=Android, C=US
        Issuer: CN=Android Debug, O=Android, C=US
        Serial number: 503bd581
        Valid from: Mon Aug 27 13:16:01 PDT 2012 until: Wed Aug 20 13:16:01 PDT 2042
        Certificate fingerprints:
           MD5:  1B:2B:2D:37:E1:CE:06:8B:A0:F0:73:05:3C:A3:63:DD
           SHA1: D8:AA:43:97:59:EE:C5:95:26:6A:07:EE:1C:37:8E:F4:F0:C8:05:C8
           SHA256: F3:6F:98:51:9A:DF:C3:15:4E:48:4B:0F:91:E3:3C:6A:A0:97:DC:0A:3F:B2:D2:E1:FE:23:57:F5:EB:AC:13:30
           Signature algorithm name: SHA1withRSA
           Version: 3

        Copy the SHA1 fingerprint, which is highlighted in the example above.

        Important: When you prepare to release your app to your users, follow these steps again and create a new OAuth 2.0 client ID for your production app. For production apps, use your own private key to sign the production app's .apk file. For more information, see Signing your applications.
     3. Paste the SHA1 fingerprint into the form where requested.
     4. Click Create.

     Chrome application

     You need to specify the Application ID for your Chrome app or extension. Use the Google Chrome Identity API to obtain that ID.

   iOS

   You need to specify the app's Bundle ID and App Store ID.

   • The application's Bundle ID is the bundle identifier as listed in the app's .plist file. For example: com.example.myapp.
   • The application's App Store ID is in the app's iTunes URL so long as the app was published in the Apple iTunes App Store. For example, in the app URL http://itunes.apple.com/us/app/google+/id447119634, the App Store ID is 447119634.

   Other

   The Developers Console does not require any additional information to create OAuth 2.0 credentials for other types of installed applications.

   • Public API access: A request that does not provide an OAuth 2.0 token must send an API key. The key identifies your project and provides API access, quota, and reports.

     The API supports several types of API keys. If the key type that you need does not already exist, create an API key by selecting Create New Key and then selecting the appropriate key type. Then enter the additional data for that key type and click Create.

     Server keys

     Create and use a server key if your application runs on a server. Do not use this key outside of your server code. For example, do not embed it in a web page. To prevent quota theft, restrict your key so that requests are only allowed from your servers' source IP addresses.

     Browser keys

     Create and use a browser key if your application runs on a client, such as a web browser. To prevent your key from being used on unauthorized sites, only allow referrals from domains you administer.

     iOS keys

     Create and use an iOS key if your application runs on iOS devices. Google verifies that each request originates from an iOS application that matches one of the bundle identifiers you specify. An app's .plist file contains its bundle identifier. Example: com.example.MyApp

     Android keys

     Create and use an Android key if your application runs on Android devices. To do so, you need to specify the SHA1 fingerprints and package names of the application using that key.

     1. In the Package name field, enter your Android app's package name.
     2. In a terminal, run the Keytool utility to get the SHA1 fingerprint for your digitally signed .apk file's public certificate.

        keytool -exportcert -alias androiddebugkey -keystore path-to-debug-or-production-keystore -list -v

        Note: For the debug.keystore, the password is android. For Eclipse, the debug keystore is typically located at ~/.android/debug.keystore.

        The Keytool prints the fingerprint to the shell. For example:

        $ keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore -list -v
        Enter keystore password: Type "android" if using debug.keystore
        Alias name: androiddebugkey
        Creation date: Aug 27, 2012
        Entry type: PrivateKeyEntry
        Certificate chain length: 1
        Certificate[1]:
        Owner: CN=Android Debug, O=Android, C=US
        Issuer: CN=Android Debug, O=Android, C=US
        Serial number: 503bd581
        Valid from: Mon Aug 27 13:16:01 PDT 2012 until: Wed Aug 20 13:16:01 PDT 2042
        Certificate fingerprints:
           MD5:  1B:2B:2D:37:E1:CE:06:8B:A0:F0:73:05:3C:A3:63:DD
           SHA1: D8:AA:43:97:59:EE:C5:95:26:6A:07:EE:1C:37:8E:F4:F0:C8:05:C8
           SHA256: F3:6F:98:51:9A:DF:C3:15:4E:48:4B:0F:91:E3:3C:6A:A0:97:DC:0A:3F:B2:D2:E1:FE:23:57:F5:EB:AC:13:30
           Signature algorithm name: SHA1withRSA
           Version: 3

        Copy the SHA1 fingerprint, which is highlighted in the example above.

        Important: When you prepare to release your app to your users, follow these steps again and create a new OAuth 2.0 client ID for your production app. For production apps, use your own private key to sign the production app's .apk file. For more information, see Signing your applications.
     3. Paste the SHA1 fingerprint into the form where requested.
     4. Click Create.

To keep your API keys secure, follow the best practices for securely using API keys.

After you have an API key, your application can append the query parameter key=yourAPIKey to all request URLs.

The API key is safe for embedding in URLs; it doesn't need any encoding.

Google Books IDs

You need to specify ID fields with certain API method calls. There are three types of IDs used within Google Books:

• Volume IDs - Unique strings given to each volume that Google Books knows about. An example of a volume ID is _LettPDhwR0C. You can use the API to get the volume ID by making a request that returns a Volume resource; you can find the volume ID in its id field.
• Bookshelf IDs - Numeric values given to a bookshelf in a user's library. Google provides some pre-defined shelves for every user with the following IDs:
  • Favorites: 0
  • Purchased: 1
  • To Read: 2
  • Reading Now: 3
  • Have Read: 4
  • Reviewed: 5
  • Recently Viewed: 6
  • My eBooks: 7
  • Books For You: 8 If we have no recommendations for the user, this shelf does not exist.
  Custom shelves have IDs greater than 1000. A bookshelf ID is unique for a given user, i.e., two users can have a bookshelf with the same ID that refer to different bookshelves. You can use the API to get the bookshelf ID by making a request that returns a Bookshelf resource; you can find the bookshelf ID in its id field.
• User IDs - Unique numeric values assigned to each user. These values are not necessarily the same ID value used in other Google services. Currently, the only way retrieve the user ID is to extract it from the selfLink in a Bookshelf resource retrieved with an authenticated request. Users can also obtain their own user ID from the Books site. A user cannot obtain the user ID for another user via the API or the Books site; the other user would have to share that information explicitly, by email for example.

IDs on Google Books site

The IDs you use with the Books API are the same IDs used on the Google Books site.

• Volume ID
  

  When viewing a particular volume on the site, you can find the volume ID in the id URL parameter. Here is an example:

  https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard

• Bookshelf ID
  

  When viewing a particular bookshelf on the site, you can find the bookshelf ID in the as_coll URL parameter. Here is an example:

  https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary

• User ID
  

  When viewing your library on the site, you can find the user ID in the uid URL parameter. Here is an example:

  https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list

Setting User Location

Google Books respects copyright, contract, and other legal restrictions associated with the end user's location. As a result, some users might not be able to access book content from certain countries. For example, certain books are "previewable" only in the United States; we omit such preview links for users in other countries. Therefore, the API results are restricted based on your server or client application's IP address.

Working with volumes

Performing a search

You can perform a volumes search by sending an HTTP GET request to the following URI:

https://www.googleapis.com/books/v1/volumes?q=search+terms

This request has a single required parameter:

• q - Search for volumes that contain this text string. There are special keywords you can specify in the search terms to search in particular fields, such as:
  • intitle: Returns results where the text following this keyword is found in the title.
  • inauthor: Returns results where the text following this keyword is found in the author.
  • inpublisher: Returns results where the text following this keyword is found in the publisher.
  • subject: Returns results where the text following this keyword is listed in the category list of the volume.
  • isbn: Returns results where the text following this keyword is the ISBN number.
  • lccn: Returns results where the text following this keyword is the Library of Congress Control Number.
  • oclc: Returns results where the text following this keyword is the Online Computer Library Center number.

Request

Here is an example of searching for Daniel Keyes' "Flowers for Algernon":

GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey

Note: Performing a search does not require authentication, so you do not have to provide the Authorization HTTP header with the GET request. However, if the call is made with authentication, each Volume will include user-specific information, such as purchased status.

Response

If the request succeeds, the server responds with a 200 OK HTTP status code and the volume results:

200 OK

{
 "kind": "books#volumes",
 "items": [
  {
   "kind": "books#volume",
   "id": "_ojXNuzgHRcC",
   "etag": "OTD2tB19qn4",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/_ojXNuzgHRcC",
   "volumeInfo": {
    "title": "Flowers",
    "authors": [
     "Vijaya Khisty Bodach"
    ],
   ...
  },
  {
   "kind": "books#volume",
   "id": "RJxWIQOvoZUC",
   "etag": "NsxMT6kCCVs",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/RJxWIQOvoZUC",
   "volumeInfo": {
    "title": "Flowers",
    "authors": [
     "Gail Saunders-Smith"
    ],
    ...
  },
  {
   "kind": "books#volume",
   "id": "zaRoX10_UsMC",
   "etag": "pm1sLMgKfMA",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/zaRoX10_UsMC",
   "volumeInfo": {
    "title": "Flowers",
    "authors": [
     "Paul McEvoy"
    ],
    ...
  },
  "totalItems": 3
}

Optional query parameters

In addition to the standard query parameters, you can use the following query parameters when performing a volumes search.

Download Format

You use the download parameter to restrict the returned results to volumes that have an available download format of epub by setting the to the value epub.

The following example searches for books with an epub download available:

GET https://www.googleapis.com/books/v1/volumes?q=pride+prejudice&download=epub&key=yourAPIKey

Filtering

You can use the filter parameter to restrict the returned results further by setting it the to one of the following values:

• partial - Returns results where at least parts of the text are previewable.
• full - Only returns results where all of the text is viewable.
• free-ebooks - Only returns results that are free Google eBooks.
• paid-ebooks - Only returns results that are Google eBooks with a price.
• ebooks - Only returns results that are Google eBooks, paid or free. Examples of non-eBooks would be publisher content that is available in limited preview and not for sale, or magazines.

The following example restricts search results to those available as free eBooks:

GET https://www.googleapis.com/books/v1/volumes?q=flowers&filter=free-ebooks&key=yourAPIKey

Pagination

You can paginate the volumes list by specifying two values in the parameters for the request:

• startIndex - The position in the collection at which to start. The index of the first item is 0.
• maxResults - The maximum number of results to return. The default is 10, and the maximum allowable value is 40.

Print Type

You can use the printType parameter to restrict the returned results to a specific print or publication type by setting it to one of the following values:

• all - Does not restrict by print type (default).
• books - Returns only results that are books.
• magazines - Returns results that are magazines.

The following example restricts search results to magazines:

GET https://www.googleapis.com/books/v1/volumes?q=time&printType=magazines&key=yourAPIKey

Projection

You can use the projection parameter with one of the following values to specify a predefined set of Volume fields to return:

• full - Returns all Volume fields.
• lite - Returns only certain fields. See field descriptions marked with double asterisks in the Volume reference to find out which fields are included.

The following example returns search results with limited volume information:

GET https://www.googleapis.com/books/v1/volumes?q=flowers&projection=lite&key=yourAPIKey

Sorting

By default, a volumes search request returns maxResults results, where maxResults is the parameter used in pagination (above), ordered by relevance to search terms.

You can change the ordering by setting the orderBy parameter to be one of these values:

• relevance - Returns results in order of the relevance of search terms (this is the default).
• newest - Returns results in order of most recently to least recently published.

The following example lists results by published date, newest to oldest:

GET https://www.googleapis.com/books/v1/volumes?q=flowers&orderBy=newest&key=yourAPIKey

Retrieving a specific volume

You can retrieve information for a specific volume by sending an HTTP GET request to the Volume resource URI:

https://www.googleapis.com/books/v1/volumes/volumeId

Replace the volumeId path parameter with the ID of the volume to retrieve. See the Google Books IDs section for more information on volume IDs.

Request

Here is an example of a GET request that gets a single volume:

GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?key=yourAPIKey

Note: Retrieving volume information does not require authentication, so you do not have to provide the Authorization HTTP header with the GET request. However, if the call is made with authentication, the Volume will include user-specific information, such as purchased status.

Response

If the request succeeds, the server responds with the 200 OK HTTP status code and the Volume resource requested:

200 OK

{
 "kind": "books#volume",
 "id": "zyTCAlFPjgYC",
 "etag": "f0zKg75Mx/I",
 "selfLink": "https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC",
 "volumeInfo": {
  "title": "The Google story",
  "authors": [
   "David A. Vise",
   "Mark Malseed"
  ],
  "publisher": "Random House Digital, Inc.",
  "publishedDate": "2005-11-15",
  "description": "\"Here is the story behind one of the most remarkable Internet
  successes of our time. Based on scrupulous research and extraordinary access
  to Google, ...",
  "industryIdentifiers": [
   {
    "type": "ISBN_10",
    "identifier": "055380457X"
   },
   {
    "type": "ISBN_13",
    "identifier": "9780553804577"
   }
  ],
  "pageCount": 207,
  "dimensions": {
   "height": "24.00 cm",
   "width": "16.03 cm",
   "thickness": "2.74 cm"
  },
  "printType": "BOOK",
  "mainCategory": "Business & Economics / Entrepreneurship",
  "categories": [
   "Browsers (Computer programs)",
   ...
  ],
  "averageRating": 3.5,
  "ratingsCount": 136,
  "contentVersion": "1.1.0.0.preview.2",
  "imageLinks": {
   "smallThumbnail": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=5&edge=curl&source=gbs_api",
   "thumbnail": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=1&edge=curl&source=gbs_api",
   "small": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=2&edge=curl&source=gbs_api",
   "medium": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=3&edge=curl&source=gbs_api",
   "large": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=4&edge=curl&source=gbs_api",
   "extraLarge": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=6&edge=curl&source=gbs_api"
  },
  "language": "en",
  "infoLink": "https://books.google.com/books?id=zyTCAlFPjgYC&ie=ISO-8859-1&source=gbs_api",
  "canonicalVolumeLink": "https://books.google.com/books/about/The_Google_story.html?id=zyTCAlFPjgYC"
 },
 "saleInfo": {
  "country": "US",
  "saleability": "FOR_SALE",
  "isEbook": true,
  "listPrice": {
   "amount": 11.99,
   "currencyCode": "USD"
  },
  "retailPrice": {
   "amount": 11.99,
   "currencyCode": "USD"
  },
  "buyLink": "https://books.google.com/books?id=zyTCAlFPjgYC&ie=ISO-8859-1&buy=&source=gbs_api"
 },
 "accessInfo": {
  "country": "US",
  "viewability": "PARTIAL",
  "embeddable": true,
  "publicDomain": false,
  "textToSpeechPermission": "ALLOWED_FOR_ACCESSIBILITY",
  "epub": {
   "isAvailable": true,
   "acsTokenLink": "https://books.google.com/books/download/The_Google_story-sample-epub.acsm?id=zyTCAlFPjgYC&format=epub&output=acs4_fulfillment_token&dl_type=sample&source=gbs_api"
  },
  "pdf": {
   "isAvailable": false
  },
  "accessViewStatus": "SAMPLE"
 }
}

Access Info

The accessInfo section is of particular interest in determining what features are available for an eBook. An epub is a flowing text format ebook, the epub section will have an isAvailable property indicating if this type of ebook is available. It will have a download link if there is a sample for the book or if the user can read the book either due to having purchased it or due to it being public domain in the user's location. A pdf for Google books indicates a scanned pages version of the ebook with similar details such as if it is available and a download link. Google recommends epub files for eReaders and SmartPhones, as scanned pages may be hard to read on these devices. If there is no accessInfo section, the volume is not available as a Google eBook.

Optional query parameters

In addition to the standard query parameters, you can use the following query parameter when retrieving a specific volume.

Projection

You can use the projection parameter with one of the following values to specify a predefined set of Volume fields to return:

• full - Returns all Volume fields.
• lite - Returns only certain fields. See field descriptions marked with double asterisks in the Volume reference to find out which fields are included.

The following example returns limited volume information for a single volume:

GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?projection=lite&key=yourAPIKey

Working with bookshelves

Retrieving a list of a user's public bookshelves

You can retrieve a list of a user's public bookshelves by sending an HTTP GET request to the URI with the following format:

https://www.googleapis.com/books/v1/users/userId/bookshelves

Replace the userId path parameter with the ID of the user whose bookshelves you would like to retrieve. See the Google Books IDs section for more information on user IDs.

Request

Here is an example:

GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves&key=yourAPIKey

Since a user does not have to be authenticated to retrieve information regarding public bookshelves, you do not have to provide the Authorization HTTP header with the GET request.

Response

If the request succeeds, the server responds with the 200 OK HTTP status code and the list of bookshelves:

200 OK

{
 "kind": "books#bookshelves",
 "items": [
  {
   ...
  },
  {
   "kind": "books#bookshelf",
   "id": 3,
   "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
   "title": "Reading now",
   "description": "",
   "access": "PUBLIC",
   "updated": "2011-02-02T20:34:20.146Z",
   "created": "2011-02-02T20:34:20.146Z",
   "volumeCount": 2,
   "volumesLastUpdated": "2011-02-02T20:34:20.110Z"
  },
  ...
 ]
}

Optional query parameters

You can use the standard query parameters when retrieving the list of a user's public bookshelves.

Retrieving a specific public bookshelf

You can retrieve a specific public bookshelf by sending an HTTP GET request to the URI with the following format:

https://www.googleapis.com/books/v1/users/userId/bookshelves/shelf

Replace the userId and shelf path parameters with the IDs that specify the user and the bookshelf you want to retrieve. See the Google Books IDs section for more information.

Request

Here is an example:

GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3?key=yourAPIKey

Since a user does not have to be authenticated to retrieve information regarding public bookshelves, you do not have to provide the Authorization HTTP header with the GET request.

Response

If the request succeeds, the server responds with the 200 OK HTTP status code and the bookshelf resource:

200 OK

{
  "kind": "books#bookshelf",
  "id": 3,
  "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
  "title": "Reading now",
  "description": "",
  "access": "PUBLIC",
  "updated": "2011-02-02T20:34:20.146Z",
  "created": "2011-02-02T20:34:20.146Z",
  "volumeCount": 2,
  "volumesLastUpdated": "2011-02-02T20:34:20.110Z"
}

Optional query parameters

You can use the standard query parameters when retrieving a specific public bookshelf.

Retrieving a list of volumes on a public bookshelf

You can retrieve a list of volumes on a user's public bookshelf by sending an HTTP GET request the a URI with the following format:

https://www.googleapis.com/books/v1/user/userId/bookshelves/shelf/volumes

Request

Here is an example:

GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3/volumes?key=yourAPIKey

Replace the userId and shelf path parameters with the IDs that specify the user and the bookshelf you want to retrieve. See the Google Books IDs section for more information.

Since a user does not have to be authenticated to retrieve information regarding public bookshelves, you do not have to provide the Authorization HTTP header with the GET request.

Response

If the request succeeds, the server responds with a 200 OK HTTP status code and the list of the user's bookshelves:

200 OK

{
 "kind": "books#volumes",
 "items": [
  {
   "kind": "books#volume",
   "id": "AZ5J6B1-4BoC",
   "etag": "kIzQA7IUObk",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/AZ5J6B1-4BoC",
   "volumeInfo": {
    "title": "The Girl Who Kicked the Hornet's Nest",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2010-05-25",
    ...
  },
  {
   "kind": "books#volume",
   "id": "UvK1Slvkz3MC",
   "etag": "otKmdbRgdFQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/UvK1Slvkz3MC",
   "volumeInfo": {
    "title": "The Girl who Played with Fire",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2009-07-28",
    ...
  },
  {
   "kind": "books#volume",
   "id": "OBM3AAAAIAAJ",
   "etag": "xb47kTr8HsQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/OBM3AAAAIAAJ",
   "volumeInfo": {
    "title": "The Sign of Four",
    "authors": [
     "Sir Arthur Conan Doyle"
    ],
    "publishedDate": "1890",
    ...
  }
 ],
 "totalItems": 3
}

Optional query parameters

In addition to the standard query parameters, you can use the following query parameter when retrieving a list of volumes on a public bookshelf.

Pagination

You can paginate the volumes list by specifying two values in the parameters for the request:

• startIndex - The position in the collection at which to start. The index of the first item is 0.
• maxResults - The maximum number of results to return. The default is 10, and the maximum allowable value is 40.

Working with bookshelves in "My Library"

All "My Library" requests apply to the authenticated user's data.

Retrieving a list of my bookshelves

You can retrieve a listing of all of the authenticated user's bookshelves by sending an HTTP GET request to the URI with the following format:

https://www.googleapis.com/books/v1/mylibrary/bookshelves

Request

Here is an example:

GET https://www.googleapis.com/books/v1/mylibrary/bookshelves?key=yourAPIKey
Authorization: /* auth token here */

Note: The user must be authenticated to retrieve a listing of "My Library" bookshelves. So you must provide the Authorization HTTP header with the GET request.

Response

If the request succeeds, the server responds with the 200 OK HTTP status code and the list of all bookshelves for the current authenticated user:

200 OK

{
 "kind": "books#bookshelves",
 "items": [
  {
   "kind": "books#bookshelf",
   "id": 0,
   "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/0",
   "title": "Favorites",
   "access": "PRIVATE",
   "updated": "2011-04-22T04:03:15.416Z",
   "created": "2011-04-22T04:03:15.416Z",
   "volumeCount": 0,
   "volumesLastUpdated": "2011-04-22T04:03:17.000Z"
  },
  {
   "kind": "books#bookshelf",
   "id": 3,
   "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
   "title": "Reading now",
   "access": "PUBLIC",
   "updated": "2010-11-11T19:44:22.377Z",
   "created": "2010-11-11T19:44:22.377Z",
   "volumeCount": 1,
   "volumesLastUpdated": "2010-11-11T19:44:22.341Z"
  }
 ]
}

Optional query parameters

You can use the standard query parameters when retrieving the list of the authenticated user's bookshelves.

Retrieving a list of volumes on my bookshelf

You can retrieve a listing of the volumes on the authenticated user's bookshelf by sending an HTTP GET request to the URI with the following format:

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/volumes

Replace the shelf path parameter with the ID of the bookshelf. See the Google Books IDs section for more information on bookshelf IDs.

Request

Here is an example:

GET https://www.googleapis.com/books/v1/mylibrary/bookshelves/7/volumes?key=yourAPIKey
Authorization: /* auth token here */

Note: The user must be authenticated to retrieve a listing of "My Library" volumes. So you must provide the Authorization HTTP header with the GET request.

Response

If the request succeeds, the server responds with the 200 OK HTTP status code and list of bookshelf volumes:

200 OK

{
 "kind": "books#volumes",
 "items": [
  {
   "kind": "books#volume",
   "id": "AZ5J6B1-4BoC",
   "etag": "kIzQA7IUObk",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/AZ5J6B1-4BoC",
   "volumeInfo": {
    "title": "The Girl Who Kicked the Hornet's Nest",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2010-05-25",
    ...
  },
  {
   "kind": "books#volume",
   "id": "UvK1Slvkz3MC",
   "etag": "otKmdbRgdFQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/UvK1Slvkz3MC",
   "volumeInfo": {
    "title": "The Girl who Played with Fire",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2009-07-28",
    ...
  },
  {
   "kind": "books#volume",
   "id": "OBM3AAAAIAAJ",
   "etag": "xb47kTr8HsQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/OBM3AAAAIAAJ",
   "volumeInfo": {
    "title": "The Sign of Four",
    "authors": [
     "Sir Arthur Conan Doyle"
    ],
    "publishedDate": "1890",
    ...
  }
 ],
 "totalItems": 3
}

Optional query parameters

In addition to the standard query parameters, you can use the following query parameter when retrieving a list of volumes on one of the authenticated user's bookshelves.

Pagination

You can paginate the volumes list by specifying two values in the parameters for the request:

• startIndex - The position in the collection at which to start. The index of the first item is 0.
• maxResults - The maximum number of results to return. The default is 10.

Adding a volume to my bookshelf

To add a volume to the authenticated user's bookshelf, send an HTTP POST request to the URI with the following format:

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/addVolume

Replace the shelf path parameter with the ID of the bookshelf. See the Google Books IDs section for more information on bookshelf IDs.

The request has a single required query parameter:

• volumeId - The ID of the volume. See the Google Books IDs section for more information on volume IDs.

Request

Here is an example to add "Flowers for Algernon" to the "Favorites" bookshelf:

POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/addVolume?volumeId=NRWlitmahXkC&key=yourAPIKey
Authorization: /* auth token here */
Content-Type: application/json
Content-Length: CONTENT_LENGTH

Note: The user must be authenticated to make modifications to a bookshelf, so you must provide the Authorization HTTP header with the POST request. No data, however, is required with this POST.

Response

If the request succeeds, the server responds with the 204 No Content HTTP status code.

Optional query parameters

You can use the standard query parameters when adding a volume to one of the authenticated user's bookshelves.

Removing a volume from my bookshelf

To remove a volume from the authenticated user's bookshelf, send an HTTP POST to the URI with the following format:

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/removeVolume

Replace the shelf path parameter with the ID of the bookshelf. See the Google Books IDs section for more information on bookshelf IDs.

The request has a single required query parameter:

• volumeId - The ID of the volume. See the Google Books IDs section for more information on volume IDs.

Request

Here is an example to remove "Flowers for Algernon" from the "Favorites" bookshelf:

POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/removeVolume?volumeId=NRWlitmahXkC&key=yourAPIKey
Authorization: /* auth token here */
Content-Type: application/json
Content-Length: CONTENT_LENGTH

Note: The user must be authenticated to make modifications to a bookshelf, so you must provide the Authorization HTTP header with the POST request. No data, however, is required with this POST.

Response

If the request succeeds, the server responds with a 204 No Content status code.

Optional query parameters

You can use the standard query parameters when removing a volume from one of the authenticated user's bookshelves.

Clearing all volumes from my bookshelf

To remove all of the volumes from the authenticated user's bookshelf, send an HTTP POST to the URI with the following format:

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/clearVolumes

Replace the shelf path parameter with the ID of the bookshelf. See the Google Books IDs section for more information on bookshelf IDs.

Request

Here is an example to clear the "Favorites" bookshelf:

POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/clearVolumes?key=yourAPIKey
Authorization: /* auth token here */
Content-Type: application/json
Content-Length: CONTENT_LENGTH
  

Note: The user must be authenticated to make modifications to a bookshelf, so you must provide the Authorization HTTP header with the POST request. No data, however, is required with this POST.

Response

If the request succeeds, the server responds with a 204 No Content status code.

Optional query parameters

You can use the standard query parameters when clearing all volumes from one of the authenticated user's bookshelves.

Query parameter reference

The query parameters you can use with the Books API are summarized in this section.  All parameter values need to be URL encoded.

Standard query parameters

Query parameters that apply to all Books API operations are shown in the table below.

Notes (on API keys and auth tokens):

1. The key parameter is required with every request, unless you provide an OAuth 2.0 token with the request.
2. You must send an authorization token with every request that is marked (AUTHENTICATED). OAuth 2.0 is the preferred authorization protocol.
3. You can provide an OAuth 2.0 token with any request in one of two ways:
   • Using the access_token query parameter like this: ?access_token=oauth2-token
   • Using the HTTP Authorization header like this: Authorization: Bearer oauth2-token

All parameters are optional except where noted.

Parameter	Meaning	Notes
access_token	OAuth 2.0 token for the current user.	One possible way to provide an OAuth 2.0 token.
callback	Callback function.	Name of the JavaScript callback function that handles the response. Used in JavaScript JSON-P requests.
fields	Selector specifying a subset of fields to include in the response.	For more information, see the partial response section in the Performance Tips document. Use for better performance.
key	API key. (REQUIRED*)	*Required unless you provide an OAuth 2.0 token. Your API key identifies your project and provides you with API access, quota, and reports. Obtain your project's API key from the Google Developers Console.
prettyPrint	Returns response with indentations and line breaks.	Returns the response in a human-readable format if true. Default value: true. When this is false, it can reduce the response payload size, which might lead to better performance in some environments.
quotaUser	Alternative to userIp.	Lets you enforce per-user quotas from a server-side application even in cases when the user's IP address is unknown. This can occur, for example, with applications that run cron jobs on App Engine on a user's behalf. You can choose any arbitrary string that uniquely identifies a user, but it is limited to 40 characters. Overrides userIp if both are provided. Learn more about capping usage.
userIp	IP address of the end user for whom the API call is being made.	Lets you enforce per-user quotas when calling the API from a server-side application. Learn more about capping usage.

API-specific query parameters

Request parameters that apply only to specific operations in the Books API are summarized in the following table.

Parameter	Meaning	Notes	Applicability
download	Restrict to volumes by download availability.	Currently, the only supported value is epub. Purchase may be required for download access.	Performing a search
filter	Filter search results by volume type and availability.	Supported filters are: filter=partial - Restrict results to volumes where at least part of the text are previewable. filter=full - Restrict results to volumes where all of the text is viewable. filter=free-ebooks - Restrict results to free Google eBooks. filter=paid-ebooks - Restrict results to Google eBooks with a price for purchase. filter=ebooks - Restrict results to Google eBooks, paid or free.Examples of non-eBooks would be publisher content that is available in limited preview and not for sale, or magazines.	Performing a search
langRestrict	Restricts the volumes returned to those that are tagged with the specified language.	Restrict the search results to those with a certain language by specifying langRestrict to a two-letter ISO-639-1 code, such as "en" or "fr".	Performing a search
maxResults	The maximum number of elements to return with this request.	For any request for all items in a collection, you can paginate results by specifying startIndex and maxResults in the parameters for the request. Default: maxResults=10 Maximum allowable value: maxResults=40.	Performing a search List user bookshelves List user bookshelf volumes List my bookshelves List my bookshelf volumes
orderBy	Order of the volume search results.	By default, a search request returns maxResults results, where maxResults is the parameter used in pagination, ordered by most relevant first. You can change the ordering by setting the orderBy parameter to be one of these values: orderBy=relevance - Returns search results in order of the most relevant to least (this is the default). orderBy=newest - Returns search results in order of the newest published date to the oldest.	Performing a search
printType	Restrict to books or magazines.	Supported values are: printType=all - Return all volume content types (no restriction). This is the default. printType=books - Return just books. printType=magazines - Return just magazines.	Performing a search
projection	Restrict volume information returned to a subset of fields.	Supported projections are: projection=full - Includes all volume metadata (default). projection=lite - Includes only a subject of volume and access metadata.	Performing a search Retrieving a volume List user bookshelf volumes List my bookshelf volumes
q	Full-text query string.	When creating a query, list search terms separated by a '+', in the form q=term1+term2_term3. (Alternatively, you can separate them with a space, but as with all of the query parameter values, the spaces must then be URL encoded.) The API returns all entries that match all of the search terms (like using AND between terms). Like Google's web search, the API searches on complete words (and related words with the same stem), not substrings. To search for an exact phrase, enclose the phrase in quotation marks: q="exact phrase". To exclude entries that match a given term, use the form q=-term. The search terms are case-insensitive. Example: to search for all entries that contain the exact phrase "Elizabeth Bennet" and the word "Darcy" but don't contain the word "Austen", use the following query parameter value: q="Elizabeth+Bennet"+Darcy-Austen There are special (case-sensitive) keywords you can specify in the search terms to search in particular fields, such as: intitle: Returns results where the text following this keyword is found in the title. inauthor: Returns results where the text following this keyword is found in the author. inpublisher: Returns results where the text following this keyword is found in the publisher. subject: Returns results where the text following this keyword is listed in the category list of the volume. isbn: Returns results where the text following this keyword is the ISBN number. lccn: Returns results where the text following this keyword is the Library of Congress Control Number. oclc: Returns results where the text following this keyword is the Online Computer Library Center number.	Performing a search
startIndex	The position in the collection at which to start the list of results.	For any request for all items in a collection, you can paginate results by specifying startIndex and maxResults in the parameters for the request. The index of the first item is 0.	Performing a search List user bookshelves List user bookshelf volumes List my bookshelves List my bookshelf volumes
volumeId	Identifies a volume associated with the request.	Specifies the volume to add or remove from a bookshelf.	Adding a volume to my bookshelf Removing a volume from my bookshelf