English | Site Directory

Google Book Search Book Viewability API

Dynamic Links - Getting Started

This chapter will help you getting started with the Book Viewability API.

Contents

  1. Audience
  2. Book Search Terminology
  3. Introduction
  4. Example API Integrations and Styling Recommendations
  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
    1. Sample 1: Using a Callback to Determine Viewability
    2. Sample 2: Linking to Individual Books
    3. Sample 3: A Touch of AJAX

Audience

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

Book Search Terminology

In order to understand this chapter, you'll need to be familiar with the terms presented in this section.

Viewability

Google Book Search respects the user's local copyright restrictions — as a result, previews or full views of some books are not available in all locations. Viewability is clustered into four 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 Book Search 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
Only short excerpts from the book are available. This book is under copyright and Google Book Search has not received permission to expose more material than we are able to use under fair use. "Search within this book" is enabled for Snippet View books, unlike Metadata View books.
Metadata View
No scan is available for this book — Google Book Search has an "About This Book" page that describes this book.

Introduction

Google Book Search historically has provided developers with the ability to link to individual titles within Google Book Search. Unfortunately, as viewability varies by geography and as the composition of the index changes (ex. we scan a new book or a publisher requests we remove a book), no one viewability state can be guaranteed to describe the user experience of all users over time or even at one moment. The Book Viewability API is not designed for off-line querying for this reason.

Instead, the Book Viewability API provides a programmatic client-side method for querying the viewability of a book using JavaScript. We believe this is the best way to ensure a consistent user experience.

Here are three examples of how the API could be used:

Example API Integrations and Styling Recommendations

The most exciting thing about APIs is that it's challenging to know how they will be used once they are released to the developer community. We would never want to limit your imagination, but to help kick you off as you integrate Google Book Search into your project, we've found a few examples of the API being used that we thought were particularly well done. If you're looking for Google Logos to use, check out the official Google Logos page.

Examples from Library Catalog Pages

Examples from Library Search Results Pages


(See a larger screenshot.)
(See a larger screenshot.)

As only public domain books are available for PDF download, we recommend against using the word "download" in your links or to describe the Google Books experience.

Client-Side API

At the core of the GBS client-side book viewability API is a URL format that allows developers to construct URLs requesting information on one or more books and send the requests to Google Book Search using the <script> tag.

Syntax Example:
<script src="http://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 currently used to link 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.

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

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

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 Book Search with information on the book (the about this book page)
preview_url
A URL to the preview of the book - this lands the user on the cover of the book. If there only Snippet View or Metadata View 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
Viewability state - either "noview", "partial", or "full"

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:
http://books.google.com/books?jscmd=viewapi&bibkeys=0596000278,00-invalid-isbn,ISBN0765304368,0439554934&callback=ProcessGBSBookInfo

Response:
ProcessGBSBookInfo({
	"0596000278":{
		"bib_key":"0596000278",
		"info_url":"http://books.google.com/books?id=ezqe1hh91q4C&source=gbs_ViewAPI",
		"preview_url":"http://books.google.com/books?id=ezqe1hh91q4C&printsec=frontcover&sig=zSQ5gwlX1NZl_24M86KS8Rbj33Q&source=gbs_ViewAPI",
		"thumbnail_url":"http://books.google.com/books?id=ezqe1hh91q4C&pg=PR3&img=1&zoom=5&sig=bBmzIAIiCtMcM7Ii7TUHycqqEWg",
		"preview":"partial"
	},
	"ISBN0765304368":{
		"bib_key":"ISBN0765304368",
		"info_url":"http://books.google.com/books?id=gfg13CM_kU8C&source=gbs_ViewAPI",
		"preview_url":"http://books.google.com/books?id=gfg13CM_kU8C&printsec=frontcover&sig=jIrSb_SkcQRhy_VvtnKbTXjmvos&source=gbs_ViewAPI",
		"thumbnail_url":"http://books.google.com/books?id=gfg13CM_kU8C&pg=PP1&img=1&zoom=5&sig=LsTwGVAsy_qWYMPM6HVDTPAMokg",
		"preview":"full"
	},
	"0439554934":{
		"bib_key":"0439554934",
		"info_url":"http://books.google.com/books?id=iwiYGwAACAAJ&source=gbs_ViewAPI",
		"preview_url":"http://books.google.com/books?id=iwiYGwAACAAJ&source=gbs_ViewAPI",
		"thumbnail_url":"http://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 Book Search.
callback
Name of the JavaScript function we pass the return to.

Synchronous vs. Asynchronous Mode

Asynchronous Mode

In Asynchronous Mode, the partner places the <script> tag in the of the document and constructs the URL will all the identifiers that are needed for rendering the page. The data is recieved from the call in a variable. This makes the the books 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 partner uses the URL in the middle of the HTML-body and 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 the Viewability API?
A: No API key or other authorization is needed to use the Viewability API. 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 Book Search has a book when a user's browser does not have JavaScript enabled. We recommend using Google Book Search's static link structure for browsers without Javascript, but remind you that you will not know in advance whether or not Google Book Search 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 uniform resource locator (URL) length of 2,083 characters which applies to GETs.
Q: Google Book Search was returning results for a book just a moment ago, but no longer is.
A: Because developers often issue an atypical quantity of requests, you may accidentially tip the security precautions found in Google Book Search. 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 Book Search (http://books.google.com) 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 the Viewability API.

Code Samples

Sample 1: Using a Callback to Determine Viewability

<html>
  <head>
    <title>Viewability API with a callback example</title>
    <link rel="stylesheet" type="text/css" href="http://code.google.com/css/dev_docs.css"> 

    <script>
      // Function to process GBS info and update the DOM.
      function ProcessGBSBookInfo(booksInfo) {
        for (isbn in booksInfo) {
         var element = document.getElementById(isbn);
         var bookInfo = booksInfo[isbn];
	     if (bookInfo) {
           element.href = bookInfo.preview_url;
           if (bookInfo.preview == "full" ||
               bookInfo.preview == "partial") {
             element.style.display = '';
          }
         }
       }
     }
    </script>
  </head>
  <body>

   <h1>Book Links</h1>

   <p>Here are a list of my favorite books. You should really check them out!</p>
   <br/>
   <table>
     <thead>
      <tr>
        <th>Name</th>
        <th>ISBN</th>
        <th colspan="2">Links</th>

      </tr>
     </thead>
     <tbody>
      <tr>
        <td>Programming Perl</td>
        <td>0596000278</td>
        <td><a href="http://amazon.com/gp/product/0596000278">Amazon</a></td>
        <td><a id="0596000278" 
            style="display:none;">Browse on Google Book Search</a></td>
      </tr>
      <tr>
        <td>Alice in Wonderland (First edition!)</td>
        <td>00-no-isbn</td>
        <td><a href="http://amazon.com/gp/product/00-no-isbn">Amazon</a></td>
        <td><a id="00-no-isbn" 
             style="display:none;">Browse on Google Book Search</a></td>
            
      </tr>
      <tr>
        <td>Down & Out</td>

        <td>ISBN0765304368</td>
        <td><a href="http://amazon.com/gp/product/ISBN0765304368">Amazon</a></td>
        <td><a id="ISBN0765304368"
            style="display:none;">Browse on Google Book Search</a></td>
      </tr>
      <tr>

        <td>Harry Potter</td>
        <td>0439554934</td>
        <td><a href="http://amazon.com/gp/product/0439554934">Amazon</a></td>
        <td><a id=0439554934 
            style="display:none;">Browse on Google Book Search</a></td>
      </tr>

     </tbody>
   </table>
   <br>
   
    <!-- Send request to Google Book Search server -->
    <script src="http://books.google.com/books?jscmd=viewapi&bibkeys=0596000278,00-no-isbn,ISBN0765304368,0439554934&callback=ProcessGBSBookInfo">
    </script>
  </body>
</html>

Sample 2: Synchronous Call to retrieve Viewability

   
<html>
  <head>
    <title>Simple HTML to fetch viewability info from books.google.com</title>
   <link rel="stylesheet" type="text/css" href="http://code.google.com/css/dev_docs.css"> 
   <style type="text/css">
   .book { margin:1em 0pt 0pt 25px; width:50em; border-bottom: 1px solid #ccc;}
   .book-title { text-decoration: underline; }
   .book p {margin-bottom: 1em;
</style>
  </head>
  <body>
    <h2>My book site</h2>

   <p>For this class, we recommend that you have at least the following
   books:</p> 
   <div id=0596000278 class="book">
      <p class="book-title">Programming Perl</p>
      <p>Larry Wall, Tom Christiansen, Jon Orwant. O'Reilly, 2000. ISBN 0596000278</p>
   </div>
   <div id=00-no-isbn class="book">
      <p class="book-title">Your course reader</u></p>
      <p>Your Esteemed Professor. self-published, 2008.</p>
   </div>
   <div id=ISBN0765304368 class="book">
      <p class="book-title">Down & Out in the Magic Kingdom</u><p>
      <p>Cory Doctorow. Macmillan, 2003. ISBN 0765304368</p>
   </div>
   <div id=0439554934 class="book">
      <p class="book-title">Harry Potter</u></p>
      <p>J. K. Rowling. Scholastic, 2003. ISBN 0439554934</p>
   </div>. 
   <p>All other books in the syllabus are optional.</p>

    <script>
      // Construct URL along with required ISBNs
      var isbns = ["0596000278", "00-no-isbn", "ISBN0765304368", "0439554934"];
      var api_url ="http://books.google.com/books?jscmd=viewapi&bibkeys=" +
         isbns.join(",");

      // Talk to the server synchronously and get _GBSBookInfo object
      document.write(unescape("%3Cscript src=" + api_url +
        " type='text/javascript'%3E%3C/script%3E"));
    </script>
    <script>
      // Process response from Google booksearch
      for (i in isbns) {
        var element = document.getElementById(isbns[i]);
        var bookInfo = _GBSBookInfo[isbns[i]];
        // Check whether  server returned any data
         if (bookInfo) {
			 if (!element) { alert (isbn); }
				element.href = bookInfo.preview_url;
				if (bookInfo.preview == "full" ||
					bookInfo.preview == "partial") {
			 
				  element.innerHTML ="<img style=\" float: right; margin: 0 0 10px 10px; border: 1px solid #666; padding: 2px;\" border=0 src=" + 
						   bookInfo.thumbnail_url + " >" + "<p><a href=\"" + bookInfo.preview_url +
						   "\">" + element.childNodes[1].innerHTML + "</a><br>" +
						   element.childNodes[3].innerHTML + "</p>" + "<div style=\"clear: both;\"></div>";
			   }
         }
      }
    </script>
  </body>

</html>

Sample 3: A Touch of AJAX

<html>
  <head>
  <link rel="stylesheet" type="text/css" href="http://code.google.com/css/dev_docs.css"> 
  
  <style type="text/css">
     .thumbnail { float: left; width: 6em; border: 1px solid #999;
               margin: 3em 1em 1em 0em; padding: 5px; text-align: center;}
     .thumbnail img { border: 1px solid #aaa; }
     .thumbnail p { margin:0em 0em 0em 0em; }
     .clearboth { clear: both; }
  </style>
  
  <title>Sample Using Google Books API JSON Output</title>
  <script>
  <!--
  /**
   * This function is the call-back function for the JSON scripts which 
   * executes a Google book search response.
   *
   * @param {JSON} booksInfo is the JSON object pulled from the Google Book Search service.
   */
  function listEntries(booksInfo) {
    // Clear any old data to prepare to display the Loading... message.
    var div = document.getElementById("data");
    if (div.firstChild) div.removeChild(div.firstChild);
  
    var mainDiv = document.createElement("div");
    
    for (i in booksInfo) {
     // Create a DIV for each book
       var book = booksInfo[i];
       var thumbnailDiv = document.createElement("div");
       thumbnailDiv.className = "thumbnail";
  
     // Add a link to each book's information page
   	var a = document.createElement("a");
        a.href = book.info_url;
        a.innerHTML = book.bib_key ;
  
     // Display a thumbnail of the book's cover
        var img = document.createElement("img");
        img.src = book.thumbnail_url;    
        a.appendChild(img);
  
        thumbnailDiv.appendChild(a);
  
     // Alert the user that the book is not previewable
        var p = document.createElement("p");
        p.innerHTML = book.preview;
        if (p.innerHTML == "noview"){
          p.style.fontWeight = "bold";
          p.style.color = "#f00";   
        }
  
     thumbnailDiv.appendChild(p);
       mainDiv.appendChild(thumbnailDiv);
    }
    
    div.appendChild(mainDiv);
  
  }
  
  /**
   *
   * @param {DOM object} query The form element containing the
   *                     input parameters "isbns"
   */
  function search(query) {
    // Clear any old data to prepare to display the Loading... message.
    var div = document.getElementById("data");
    if (div.firstChild) div.removeChild(div.firstChild);
  
    // Show a "Loading..." indicator.
    var div = document.getElementById('data');
    var p = document.createElement('p');
    p.appendChild(document.createTextNode('Loading...'));
    div.appendChild(p);
  
    // Delete any previous Google Book Search JSON queries.
    var jsonScript = document.getElementById("jsonScript");
    if (jsonScript) {
      jsonScript.parentNode.removeChild(jsonScript);
      }
        
    // Add a script element with the src as the user's Google Book Search query. 
    // JSON output is specified by including the alt=json-in-script argument
    // and the callback function is also specified as a URI argument.
    var scriptElement = document.createElement("script");
    scriptElement.setAttribute("id", "jsonScript");
    scriptElement.setAttribute("src",
        "http://books.google.com/books?bibkeys=" + 
        escape(query.isbns.value) + "&jscmd=viewapi&callback=listEntries");
    scriptElement.setAttribute("type", "text/javascript");
    // make the request to Google Book Search
    document.documentElement.firstChild.appendChild(scriptElement);
    }
  
  //-->
  </script>
  </head>
  <body>
      <h2>Sample Using Google Book Search API JSON Output</h2>
      <p>
      <h3>Introduction</h3></p>
      <form onSubmit="return false">
        <p>Google Viewability API: 
          Query: <input type="text" name="isbns" value="0064430073, 0064430065, 0606018034, 0606011234">
          <button id="search_button" onClick="search(this.form)">Search</button></p>
      </form>
      <div id="data" style="margin-left: 5em;"></div>
    </body>
</html>