Dynamic Links

The Google Books Dynamic Links feature allows you to create more customizable, reliable links to Google Books from your site. For example, this tool lets you generate "smart" links that appear only when a book is in our index, or display links that indicate to your users whether a book can be previewed on Google Books. The Dynamic Links feature also lets you include a thumbnail image in your link to Google Books. This document is intended to let you quickly add this functionality to your site.

Note: This feature was formerly known as the the Book Viewability API.

The Preview Wizard is a tool built atop Dynamic Links that makes it even easier to link to book previews from site by just copying a few lines of code. This document is intended for more advanced developers looking to customize how they link to Book Search.

Contents

  1. Audience
  2. Book Search terminology
  3. Introduction
  4. Branding guidelines
  5. The Client-side API
    1. Request URL format
    2. JSON results format
  7. Synchronous and asynchronous modes
  8. Frequently asked questions
  9. Code samples

Audience

The dynamic links documentation is intended for programmers who want to write web applications that link to books within Google Books. This documentation assumes that you are familiar with the HTTP protocol and basic JavaScript.

Book Search terminology

Google Books respects the user's local copyright restrictions, and as a result, previews or full views of some books are not available in all locations. Viewability is clustered into the following classes:

Full View
The entire book is viewable. These books may be in the public domain.
Limited Preview
A portion of the book is viewable. This book is under copyright and Google Books has received permission to make these pages accessible to users. These books differ from Snippet View books in that users may view entire pages.
Snippet View and No Preview
Users see only an "About the book" page. At most, only short excerpts from the book are available. This book has either not been scanned, or is under copyright and Google Books has not received permission to expose more than a few "snippets" related to a user's search term.

Introduction

The Static Links documentation describes a very simple way of generating URLs to a particular book's page on Google Books. Unfortunately, it is sometimes the case that a particular book is not in the Google Books index, or that a preview is not available to a user in a particular geographic location. Because Static Links are "blind," they sometimes fail to have the intended effect.

Dynamic Links provides an alternative, programmatic client-side method for querying the viewability of a book using JavaScript. This allows you to include more reliable and predictable links to Book Search, leading to a more consistent experience for your users. Because viewability varies according to the end user's location, the dynamic link interface is not designed for server-side or offline queries.

To get a sense of what Dynamic Links can do, skip to the code samples at the end of this document.

Branding guidelines

When rendering Dynamic Links, you must abide by the branding guidelines that govern the Google Books API Family. In particular,

  • You must maintain attribution and links to Google Books.
  • You must use only the approved Google Preview button when linking to previews on Google Books.
  • Any text links, buttons, documentation, or descriptive text should abide by the approved naming conventions. For example, you should not use the verbs "download" or "read" when linking to Google Books previews, as only public domain works can be downloaded in their entirety.

Example branding

Freakonomics: An Rogue Economist Explores the Hidden Side of Everything
By Steven Levitt and Stephen Dubner

The samples section at the end of this document provides additional examples that are compliant with the current branding guidelines.

Client-side API

At the core of the client-side dynamic link is a URL format that allows developers to construct URLs requesting information on one or more books and send the requests to Google Books using the <script> tag.

Syntax Example:
<script src="https://books.google.com/books?bibkeys=ISBN:0451526538&jscmd=viewapi&callback=mycallback"></script>

Request format

The format of the URL is similar to the URL syntax used to link to books, but the book ID field may contain multiple comma separated book IDs and there are additional 'jscmd' and 'callback' parameters. Optionally, additional arguments can be present to control the viewability filters.

Dynamic Links supports several different methods for identifying books: ISBNs, OCLC numbers, and LCCN keys. The API allows batched queries of up to the size of the max size of a GET request.

ISBN
&bibkeys=ISBN:0451526538 (The API supports both ISBN 10 and 13.)
OCLC
&bibkeys=OCLC:36792831
LCCN
&bibkeys=LCCN:96072233

JSON results format

The response from this call will be information about the requested books returned as one or more JSON objects. The JSON objects use the following structure:

JsonSearchResult {
    string bib_key;
    string info_url;
    string preview_url;
    string thumbnail_url;
    string preview;
};

These fields provide the following information:

bib_key
The identifier used to query this book.
info_url
A URL to a page within Google Books with information on the book (the about this book page).
preview_url
A URL to the preview of the book, which takes the user directly to the cover of the book. If only Snippet View or No Preview books available for a request, no preview URL will be returned.
thumbnail_url
A URL to a thumbnail of the cover of the book.
preview
A value indicating the viewability state of the book: full (for Full View books), partial (for Limited Preview books), or noview (for Snippet or No Preview books).
embeddable
This boolean is true if the book can be embedded onto third party pages using the Book Search embedded viewer.

The response is a JSON object with two fields, "books" which has a value of a map of book objects and "options" which contains a list of the options enabled for that request. If no options were specified, the "options" field may be omitted in the response. For example:

Request:
https://books.google.com/books?jscmd=viewapi&bibkeys=0596000278,00-invalid-isbn,ISBN0765304368,0439554934&callback=ProcessGBSBookInfo

Response:
ProcessGBSBookInfo({
    "0596000278":{
        "bib_key":"0596000278",
        "info_url":"https://books.google.com/books?id=ezqe1hh91q4C&source=gbs_ViewAPI",
        "preview_url":"https://books.google.com/books?id=ezqe1hh91q4C&printsec=frontcover&sig=zSQ5gwlX1NZl_24M86KS8Rbj33Q&source=gbs_ViewAPI",
        "thumbnail_url":"https://books.google.com/books?id=ezqe1hh91q4C&pg=PR3&img=1&zoom=5&sig=bBmzIAIiCtMcM7Ii7TUHycqqEWg",
        "preview":"partial"
    },
    "ISBN0765304368":{
        "bib_key":"ISBN0765304368",
        "info_url":"https://books.google.com/books?id=gfg13CM_kU8C&source=gbs_ViewAPI",
        "preview_url":"https://books.google.com/books?id=gfg13CM_kU8C&printsec=frontcover&sig=jIrSb_SkcQRhy_VvtnKbTXjmvos&source=gbs_ViewAPI",
        "thumbnail_url":"https://books.google.com/books?id=gfg13CM_kU8C&pg=PP1&img=1&zoom=5&sig=LsTwGVAsy_qWYMPM6HVDTPAMokg",
        "preview":"full"
    },
    "0439554934":{
        "bib_key":"0439554934",
        "info_url":"https://books.google.com/books?id=iwiYGwAACAAJ&source=gbs_ViewAPI",
        "preview_url":"https://books.google.com/books?id=iwiYGwAACAAJ&source=gbs_ViewAPI",
        "thumbnail_url":"https://books.google.com/books?id=iwiYGwAACAAJ&printsec=frontcover&img=1&zoom=5&sig=_L6ySKDAs-8gNK28c3NyFdO22ZM",
        "preview":"noview"}
});

Developers may then change the content and appearance of their web pages based on the JSON results retrieved from the GBS server. At this time, GBS does not provide libraries for modifying the DOM to do this.

Parameters and additional fields

jscmd
The request to Google Books.
callback
Name of the JavaScript function we pass the return to.

Synchronous vs. asynchronous mode

Asynchronous mode

In Asynchronous Mode, the developer places the <script> tag in the <head> of the document and constructs the URL with all the identifiers that are needed for rendering the page. The data is received from the call in a variable. This makes the book's information available to the rest of the document and it can be accessed immediately in the HTML and JavaScript.

Synchronous mode

In Synchronous mode, the developer uses the URL in the middle of the HTML <body>; the response is handled using a JavaScript callback.

Frequently asked questions

Q: Do I need an API key or other permission in order to use dynamic links?
A: No API key or other authorization is needed to use dynamic links. To get started, just copy and paste one of our examples and start tinkering.
Q: What about browsers that either don't support JavaScript or have it disabled?
A: There is no way to test whether or not Google Books has a book when a user's browser does not have JavaScript enabled. We recommend using Google Books's static link structure for browsers without JavaScript, but remember that you cannot know in advance whether Google Books has the book you are linking to.
Q: How many books can I search for at once?
A: The number of books you can search for is only limited by the length of GET requests. In Microsoft Internet Explorer, the maximum URL length (2,083 characters) limits the length of GET requests.
Q: Google Books was returning results for a book just a moment ago. Why isn't it returning results now?
A: Because developers often issue an atypical quantity of requests, you may accidentially tip the security precautions found in Google Books. To check to see if this is happening, view what is being returned by the API. If it is a request to fill out a captcha, you have issued too many queries. We recommend logging into Google Books and trying again.
Q: What about privacy?
A: In answering queries for book viewability, Google receives non-personally identifiable server log data. We take user privacy seriously and treat this data as described in our Privacy Policy. If you are providing users with a service that includes book viewability, you may want to let your users know that your service also submits queries to Google through dynamic links.

Code samples

This section provides samples that illustrate different ways of using Dynamic Links. You can click any example to see it in action. To see the underlying code, "view source" from your browser.

  • Preview button for a book page
    If you intend to use Dynamic Links to add "preview" buttons to individual book pages on your site, this is the example for you. This implementation uses a synchronous call to Google Books.
  • Course reading list
    This example shows a typical book list for an academic course. We use a single synchronous call to link to book pages on Google Books, add cover images, and indicate preview availability.
  • Alternate book list
    Similar to the prior example, this sample adds links to Book Search using an asynchronous API callback.
  • Interactive AJAX
    You may be interested in using Dynamic Links in a highly interactive, AJAX application. This example shows how to issue a number of different calls without refreshing the page.