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. Show
If you're unfamiliar with Google Books concepts, you should read Getting Started before starting to code. Authorizing requests and identifying your applicationEvery 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 (which also authorizes the request) and/or using the application's . Here's how to determine which of those options to use:
About authorization protocolsYour application must use OAuth 2.0 to authorize requests. No other authorization protocols are supported. If your application uses Sign In With Google, some aspects of authorization are handled for you. Authorizing requests with OAuth 2.0Requests 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:
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 keyRequests 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:
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 https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list7 to all request URLs. The API key is safe for embedding in URLs; it doesn't need any encoding. Google Books IDsYou need to specify ID fields with certain API method calls. There are three types of IDs used within Google Books:
IDs on Google Books siteThe IDs you use with the Books API are the same IDs used on the Google Books site.
Setting User LocationGoogle 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 volumesPerforming a searchYou can perform a volumes search by sending an HTTP https://www.googleapis.com/books/v1/volumes?q=search+terms4 request to the following URI: https://www.googleapis.com/books/v1/volumes?q=search+terms This request has a single required parameter:
RequestHere 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 GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey3 HTTP header with the https://www.googleapis.com/books/v1/volumes?q=search+terms4 request. However, if the call is made with authentication, each Volume will include user-specific information, such as purchased status. ResponseIf the request succeeds, the server responds with a GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey5 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 parametersIn addition to the , you can use the following query parameters when performing a volumes search. Download FormatYou use the GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey6 parameter to restrict the returned results to volumes that have an available download format of GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey7 by setting theto the value GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey7. 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 FilteringYou can use the GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey9 parameter to restrict the returned results further by setting it the to one of the following values:
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 PaginationYou can paginate the volumes list by specifying two values in the parameters for the request:
Print TypeYou can use the 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 }7 parameter to restrict the returned results to a specific print or publication type by setting it to one of the following values:
The following example restricts search results to magazines: GET https://www.googleapis.com/books/v1/volumes?q=time&printType=magazines&key=yourAPIKey ProjectionYou can use the GET https://www.googleapis.com/books/v1/volumes?q=pride+prejudice&download=epub&key=yourAPIKey1 parameter with one of the following values to specify a predefined set of Volume fields to return:
The following example returns search results with limited volume information: https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard0 SortingBy default, a volumes search request returns 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 }6 results, where 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 }6 is the parameter used in pagination (above), ordered by relevance to search terms. You can change the ordering by setting the GET https://www.googleapis.com/books/v1/volumes?q=pride+prejudice&download=epub&key=yourAPIKey6 parameter to be one of these values:
The following example lists results by published date, newest to oldest: https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard1 Retrieving a specific volumeYou can retrieve information for a specific volume by sending an HTTP https://www.googleapis.com/books/v1/volumes?q=search+terms4 request to the Volume resource URI: https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard2 Replace the GET https://www.googleapis.com/books/v1/volumes?q=flowers&filter=free-ebooks&key=yourAPIKey0 path parameter with the ID of the volume to retrieve. See the section for more information on volume IDs. RequestHere is an example of a https://www.googleapis.com/books/v1/volumes?q=search+terms4 request that gets a single volume: https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard3 Note: Retrieving volume information does not require authentication, so you do not have to provide the GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey3 HTTP header with the https://www.googleapis.com/books/v1/volumes?q=search+terms4 request. However, if the call is made with authentication, the Volume will include user-specific information, such as purchased status. ResponseIf the request succeeds, the server responds with the GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey5 HTTP status code and the Volume resource requested: https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard4 Access InfoThe GET https://www.googleapis.com/books/v1/volumes?q=flowers&filter=free-ebooks&key=yourAPIKey5 section is of particular interest in determining what features are available for an eBook. An GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey7 is a flowing text format ebook, the GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey7 section will have an GET https://www.googleapis.com/books/v1/volumes?q=flowers&filter=free-ebooks&key=yourAPIKey8 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 GET https://www.googleapis.com/books/v1/volumes?q=flowers&filter=free-ebooks&key=yourAPIKey9 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 GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey7 files for eReaders and SmartPhones, as scanned pages may be hard to read on these devices. If there is no GET https://www.googleapis.com/books/v1/volumes?q=flowers&filter=free-ebooks&key=yourAPIKey5 section, the volume is not available as a Google eBook. Optional query parametersIn addition to the , you can use the following query parameter when retrieving a specific volume. ProjectionYou can use the GET https://www.googleapis.com/books/v1/volumes?q=pride+prejudice&download=epub&key=yourAPIKey1 parameter with one of the following values to specify a predefined set of Volume fields to return:
The following example returns limited volume information for a single volume: https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard5 Working with bookshelvesRetrieving a list of a user's public bookshelvesYou can retrieve a list of a user's public bookshelves by sending an HTTP https://www.googleapis.com/books/v1/volumes?q=search+terms4 request to the URI with the following format: https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard6 Replace the userId path parameter with the ID of the user whose bookshelves you would like to retrieve. See the section for more information on user IDs. RequestHere is an example: https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard7 Since a user does not have to be authenticated to retrieve information regarding public bookshelves, you do not have to provide the GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey3 HTTP header with the https://www.googleapis.com/books/v1/volumes?q=search+terms4 request. ResponseIf the request succeeds, the server responds with the GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey5 HTTP status code and the list of bookshelves: https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard8 Optional query parametersYou can use the when retrieving the list of a user's public bookshelves. Retrieving a specific public bookshelfYou can retrieve a specific public bookshelf by sending an HTTP https://www.googleapis.com/books/v1/volumes?q=search+terms4 request to the URI with the following format: https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard9 Replace the userId and shelf path parameters with the IDs that specify the user and the bookshelf you want to retrieve. See the section for more information. RequestHere is an example: https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary0 Since a user does not have to be authenticated to retrieve information regarding public bookshelves, you do not have to provide the GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey3 HTTP header with the https://www.googleapis.com/books/v1/volumes?q=search+terms4 request. ResponseIf the request succeeds, the server responds with the GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey5 HTTP status code and the bookshelf resource: https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary1 Optional query parametersYou can use the when retrieving a specific public bookshelf. Retrieving a list of volumes on a public bookshelfYou can retrieve a list of volumes on a user's public bookshelf by sending an HTTP https://www.googleapis.com/books/v1/volumes?q=search+terms4 request the a URI with the following format: https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary2 RequestHere is an example: https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary3 Replace the userId and shelf path parameters with the IDs that specify the user and the bookshelf you want to retrieve. See the 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 GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey3 HTTP header with the https://www.googleapis.com/books/v1/volumes?q=search+terms4 request. ResponseIf the request succeeds, the server responds with a GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey5 HTTP status code and the list of the user's bookshelves: https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary4 Optional query parametersIn addition to the , you can use the following query parameter when retrieving a list of volumes on a public bookshelf. PaginationYou can paginate the volumes list by specifying two values in the parameters for the request:
Working with bookshelves in "My Library"All "My Library" requests apply to the authenticated user's data. Retrieving a list of my bookshelvesYou can retrieve a listing of all of the authenticated user's bookshelves by sending an HTTP https://www.googleapis.com/books/v1/volumes?q=search+terms4 request to the URI with the following format: https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary5 RequestHere is an example: https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary6 Note: The user must be authenticated to retrieve a listing of "My Library" bookshelves. So you must provide the GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey3 HTTP header with the https://www.googleapis.com/books/v1/volumes?q=search+terms4 request. ResponseIf the request succeeds, the server responds with the GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey5 HTTP status code and the list of all bookshelves for the current authenticated user: https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary7 Optional query parametersYou can use the when retrieving the list of the authenticated user's bookshelves. Retrieving a list of volumes on my bookshelfYou can retrieve a listing of the volumes on the authenticated user's bookshelf by sending an HTTP https://www.googleapis.com/books/v1/volumes?q=search+terms4 request to the URI with the following format: https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary8 Replace the shelf path parameter with the ID of the bookshelf. See the section for more information on bookshelf IDs. RequestHere is an example: https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary9 Note: The user must be authenticated to retrieve a listing of "My Library" volumes. So you must provide the GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey3 HTTP header with the https://www.googleapis.com/books/v1/volumes?q=search+terms4 request. ResponseIf the request succeeds, the server responds with the GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey5 HTTP status code and list of bookshelf volumes: https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary4 Optional query parametersIn addition to the , you can use the following query parameter when retrieving a list of volumes on one of the authenticated user's bookshelves. PaginationYou can paginate the volumes list by specifying two values in the parameters for the request:
Adding a volume to my bookshelfTo add a volume to the authenticated user's bookshelf, send an HTTP https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard19 request to the URI with the following format: https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list1 Replace the shelf path parameter with the ID of the bookshelf. See the section for more information on bookshelf IDs. The request has a single required query parameter:
RequestHere is an example to add "Flowers for Algernon" to the "Favorites" bookshelf: https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list2 Note: The user must be authenticated to make modifications to a bookshelf, so you must provide the GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey3 HTTP header with the https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard19 request. No data, however, is required with this https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard19. ResponseIf the request succeeds, the server responds with the https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard24 HTTP status code. Optional query parametersYou can use the when adding a volume to one of the authenticated user's bookshelves. Removing a volume from my bookshelfTo remove a volume from the authenticated user's bookshelf, send an HTTP https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard19 to the URI with the following format: https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list3 Replace the shelf path parameter with the ID of the bookshelf. See the section for more information on bookshelf IDs. The request has a single required query parameter:
RequestHere is an example to remove "Flowers for Algernon" from the "Favorites" bookshelf: https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list4 Note: The user must be authenticated to make modifications to a bookshelf, so you must provide the GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey3 HTTP header with the https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard19 request. No data, however, is required with this https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard19. ResponseIf the request succeeds, the server responds with a https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard24 status code. Optional query parametersYou can use the when removing a volume from one of the authenticated user's bookshelves. Clearing all volumes from my bookshelfTo remove all of the volumes from the authenticated user's bookshelf, send an HTTP https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard19 to the URI with the following format: https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list5 Replace the shelf path parameter with the ID of the bookshelf. See the section for more information on bookshelf IDs. RequestHere is an example to clear the "Favorites" bookshelf: https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list6 Note: The user must be authenticated to make modifications to a bookshelf, so you must provide the GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey3 HTTP header with the https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard19 request. No data, however, is required with this https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard19. ResponseIf the request succeeds, the server responds with a https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard24 status code. Optional query parametersYou can use the when clearing all volumes from one of the authenticated user's bookshelves. Query parameter referenceThe query parameters you can use with the Books API are summarized in this section. All parameter values need to be URL encoded. Standard query parametersQuery parameters that apply to all Books API operations are documented at System Parameters. API-specific query parametersRequest parameters that apply only to specific operations in the Books API are summarized in the following table. |