This talk is licensed under a Creative Commons, Attribution, Share Alike license and is available from http://bzr.coffeecode.net/2011_olita .

WARNING: This presentation contains (very little!) code.

DISCLAIMER: I hold (very few!) Google shares.

Google Books v1 API

Released at Google I/O start of May 2011, based on the Discovery API service
AJAX and Data APIs will die December 2011
REST calls, JSON data
Strict limits on unauthenticated access
Free authenticated access, but low default limits
Extensive documentation

Google API Console

The Google API Console appears to be Google’s one-stop shop for all of its future APIs:

Create API projects, then manage and report on:
- Authentication tokens
- API usage
- Enable and disable APIs
- Request an increased quota (default: 1000 queries/day, 1 qps/user)
Check the terms of service

A fast happy response

The API is fast, and Google’s customer service can be as well.

A few hours after submitting a request for a quota increase:

A word about authentication

Depending on the operation, either OAuth2 or append an API key as a GET param
Unless you’re an OAuth wizard, use the Google Discovery API language libraries:
- Beta:
  - Java
  - Python
- Alpha:
  - .Net
  - PHP
  - Ruby
As civilized people, we shall use Python for our examples.

Authentication screenshot

With the Python client, at least, the first time you run a script you are asked to open a URL in a browser to authorize access:

Search for matching volumes

GET https://www.googleapis.com/books/v1/volumes?q={search terms}

"{search terms}":
- AND by default
- - for exclusion
- "quote" for exact phrase
- intitle:, subject:, inauthor:, inpublisher:, isbn: to scope search
Other parameters enable you to filter by visibility, limit by download format, paginate

def vol_by_query(self, query):
    "Return the metadata for all results for a given query"

    results = self.service.volumes().list(q=query).execute()

    return results

Response for a successful search

curl 'https://www.googleapis.com/books/v1/volumes?q=apache+derby'

{
   "kind" : "books#volumes",
   "totalItems" : 597,
   "items" : [
      {
         "etag" : "6II3PsLxZfo",
         "accessInfo" : {
            "country" : "CA",
            "publicDomain" : false,
            "accessViewStatus" : "NONE",
            "viewability" : "NO_PAGES",
            "embeddable" : false
         },
         "volumeInfo" : {
            "authors" : [
               "Paul Zikopoulos",
               "George Baklarz",
               "Dan Scott"
            ],
            "imageLinks" : {
               "thumbnail" : "http://bks6.books.google.com/books?id=nrUZAAAACAAJ&printsec=frontcover&img=1&zoom=1&source=gbs_api",
               "smallThumbnail" : "http://bks6.books.google.com/books?id=nrUZAAAACAAJ&printsec=frontcover&img=1&zoom=5&source=gbs_api"
            },
            "language" : "en",
            "infoLink" : "http://books.google.com/books?id=nrUZAAAACAAJ&dq=apache+derby&ie=ISO-8859-1&source=gbs_api",
            "industryIdentifiers" : [
               {
                  "identifier" : "0131855255",
                  "type" : "ISBN_10"
               },
               {
                  "identifier" : "9780131855250",
                  "type" : "ISBN_13"
               }
            ],
            "publishedDate" : "2005-11-06",
            "previewLink" : "http://books.google.com/books?id=nrUZAAAACAAJ&dq=apache+derby&ie=ISO-8859-1&cd=1&source=gbs_api",
            "description" : "",
            "printType" : "BOOK",
            "subtitle" : "off to the races : includes details of IBM Cloudscape",
            "contentVersion" : "preview-1.0.0",
            "title" : "Apache Derby",
            "pageCount" : 567,
            "publisher" : "IBM Press"
         },
         "selfLink" : "https://www.googleapis.com/books/v1/volumes/nrUZAAAACAAJ",
         "kind" : "books#volume",
         "id" : "nrUZAAAACAAJ",
         "saleInfo" : {
            "country" : "CA",
            "saleability" : "NOT_FOR_SALE",
            "isEbook" : false
         }
      },
      {
         "etag" : "COHHnYS3RpU",
         "accessInfo" : {
            "country" : "CA",
            "publicDomain" : false,
            "accessViewStatus" : "NONE",
            "viewability" : "NO_PAGES",
            "embeddable" : false
         },
         "volumeInfo" : {
            "authors" : [
               "Lambert M Surhone",
               "Mariam T Tennoe",
               "Susan F Henssonow"
            ],
            "language" : "en",
            "infoLink" : "http://books.google.com/books?id=XDlNYgEACAAJ&dq=apache+derby&ie=ISO-8859-1&source=gbs_api",
            "industryIdentifiers" : [
               {
                  "identifier" : "6134618403",
                  "type" : "ISBN_10"
               },
               {
                  "identifier" : "9786134618403",
                  "type" : "ISBN_13"
               }
            ],
            "publishedDate" : "2010-12-14",
            "previewLink" : "http://books.google.com/books?id=XDlNYgEACAAJ&dq=apache+derby&ie=ISO-8859-1&cd=2&source=gbs_api",
            "description" : "",
            "printType" : "BOOK",
            "title" : "Apache Derby",
            "pageCount" : 100,
            "contentVersion" : "preview-1.0.0"
         },
         "selfLink" : "https://www.googleapis.com/books/v1/volumes/XDlNYgEACAAJ",
         "kind" : "books#volume",
         "id" : "XDlNYgEACAAJ",
         "saleInfo" : {
            "country" : "CA",
            "saleability" : "NOT_FOR_SALE",
            "isEbook" : false
         }
      },
      {
         "etag" : "KgL75KhIVJc",
         "accessInfo" : {
            "country" : "CA",
            "publicDomain" : false,
            "accessViewStatus" : "NONE",
            "viewability" : "NO_PAGES",
            "embeddable" : false
         },
         "volumeInfo" : {
            "authors" : [
               "Paul C. Zikopoulos",
               "George Baklarz",
               "Dan Scott"
            ],
            "imageLinks" : {
               "thumbnail" : "http://bks0.books.google.com/books?id=vBQdQwAACAAJ&printsec=frontcover&img=1&zoom=1&source=gbs_api",
               "smallThumbnail" : "http://bks0.books.google.com/books?id=vBQdQwAACAAJ&printsec=frontcover&img=1&zoom=5&source=gbs_api"
            },
            "language" : "en",
            "infoLink" : "http://books.google.com/books?id=vBQdQwAACAAJ&dq=apache+derby&ie=ISO-8859-1&source=gbs_api",
            "industryIdentifiers" : [
               {
                  "identifier" : "0137080174",
                  "type" : "ISBN_10"
               },
               {
                  "identifier" : "9780137080175",
                  "type" : "ISBN_13"
               }
            ],
            "publishedDate" : "2010-02-04",
            "previewLink" : "http://books.google.com/books?id=vBQdQwAACAAJ&dq=apache+derby&ie=ISO-8859-1&cd=3&source=gbs_api",
            "description" : "",
            "printType" : "BOOK",
            "subtitle" : "Includes Details of IBM Cloudscape",
            "contentVersion" : "preview-1.0.0",
            "title" : "Apache Derby -- Off to the Races",
            "pageCount" : 600,
            "publisher" : "IBM Pr"
         },
         "selfLink" : "https://www.googleapis.com/books/v1/volumes/vBQdQwAACAAJ",
         "kind" : "books#volume",
         "id" : "vBQdQwAACAAJ",
         "saleInfo" : {
            "country" : "CA",
            "saleability" : "NOT_FOR_SALE",
            "isEbook" : false
         }
      }
   ]
}

Add a volume to a bookshelf

Create a bookshelf using the Google Books UI in a browser
Grant access via OAuth2 to your application
POST to https://www.googleapis.com/books/v1/mylibrary/bookshelves/{shelf}/addVolume?volumeId={volumeId} with OAuth2 authentication

Where:

{shelf} is the shelf identifier
{volumeId} is the Google Books volume identifier

def add_volume(self, shelf_id, vol_id):
    """Add a volume to a user's book shelf"""

    # Requires an empty body argument? Okay.
    res = self.service.mylibrary().bookshelves().addVolume(
        body='', volumeId=vol_id, shelf=shelf_id
    ).execute(self.auth_http)

    return res

Searching a bookshelf

Not currently possible in v1 API.

Wait, what? Help!

Posted a question in Google Books API forum on May 21
Asked for help on #googleapis IRC channel; friendly, but no authorities
Opened bug #587 in google-ajax-apis bug tracker on May 26
Sent email to Google Books product manager

No response so far. A bit disappointing. But one can divine a business rationale: force people to land on the Google Books property on the web, collect more usage data, and (possibly) sell books.

OpenLibrary Read API

Released end of May 2011
REST calls (GET a single URI), JSON data
No limits on API usage
No authentication required
Limited documentation

Goal of the API

Find matching or similar editions based on identifiers
For each match, return metadata and URLs for reading online or "borrowing" (introduced June 2010)

OpenLibrary Reader

OpenLibrary downloadable formats

OpenLibrary Read API summary

All requests are GET and use the following template:

http://openlibrary.org/api/volumes/brief/json/[identifier-list]

where the [identifier-list] is a pipe-delimited set of one or more identifiers:

ISBN - (isbn:) prefix
OCLC - (oclc:) prefix
LCCN - (lccn:) prefix
OpenLibrary ID - (olid:) prefix

Results are returned in a JSON hash with keys that match your requested identifiers.

Each identifier key contains a records hash and an items array for matching bibliographic metadata and electronic resources, respectively.

OpenLibrary READ API example

curl http://openlibrary.org/api/volumes/brief/json/isbn:9780596156718|

{
   "isbn:9780596156718" : {
      "records" : {
         "/books/OL23747519M" : {
            "issns" : [],
            "lccns" : [],
            "data" : {
               "authors" : [
                  {
                     "name" : "Jono Bacon",
                     "url" : "http://openlibrary.org/authors/OL2654203A/Jono_Bacon"
                  }
               ],
               "subjects" : [
                  {
                     "name" : "project management",
                     "url" : "http://openlibrary.org/subjects/project_management"
                  }
               ],
               "pagination" : "xxv; 364",
               "number_of_pages" : 394,
               "key" : "/books/OL23747519M",
               "table_of_contents" : [
                  {
                     "level" : 0,
                     "title" : "The art of community",
                     "pagenum" : "1",
                     "label" : "1"
                  },
                  {
                     "level" : 0,
                     "title" : "Planning your community",
                     "pagenum" : "21",
                     "label" : "2"
                  },
                  {
                     "level" : 0,
                     "title" : "Communicating clearly",
                     "pagenum" : "65",
                     "label" : "3"
                  },
                  {
                     "level" : 0,
                     "title" : "Processes: simple is simple",
                     "pagenum" : "91",
                     "label" : "4"
                  },
                  {
                     "level" : 0,
                     "title" : "Supporting workflow with tools",
                     "pagenum" : "119",
                     "label" : "5"
                  },
                  {
                     "level" : 0,
                     "title" : "Building buzz",
                     "pagenum" : "145",
                     "label" : "6"
                  },
                  {
                     "level" : 0,
                     "title" : "Measuring community",
                     "pagenum" : "187",
                     "label" : "7"
                  },
                  {
                     "level" : 0,
                     "title" : "Governance",
                     "pagenum" : "211",
                     "label" : "8"
                  },
                  {
                     "level" : 0,
                     "title" : "Handling conflict",
                     "pagenum" : "267",
                     "label" : "9"
                  },
                  {
                     "level" : 0,
                     "title" : "Creating and running events",
                     "pagenum" : "301",
                     "label" : "10"
                  },
                  {
                     "level" : 0,
                     "title" : "Hiring a community manager",
                     "pagenum" : "341",
                     "label" : "11"
                  },
                  {
                     "level" : 0,
                     "title" : "Index",
                     "pagenum" : "359",
                     "label" : ""
                  }
               ],
               "identifiers" : {
                  "openlibrary" : [
                     "OL23747519M"
                  ],
                  "isbn_13" : [
                     "9780596156718"
                  ],
                  "isbn_10" : [
                     "0596156715"
                  ]
               },
               "subtitle" : "Building the New Age of Participation",
               "cover" : {
                  "large" : "http://covers.openlibrary.org/b/id/6223071-L.jpg",
                  "small" : "http://covers.openlibrary.org/b/id/6223071-S.jpg",
                  "medium" : "http://covers.openlibrary.org/b/id/6223071-M.jpg"
               },
               "publish_date" : "August 2009",
               "publishers" : [
                  {
                     "name" : "O'Reilly Media, Inc"
                  }
               ],
               "notes" : "The author has made the PDF version of his book available under a CC-BY-SA-NC Creative Commons license.",
               "publish_places" : [
                  {
                     "name" : "Sebastopol, California"
                  }
               ],
               "url" : "http://openlibrary.org/books/OL23747519M/The_Art_of_Community",
               "title" : "The Art of Community",
               "ebooks" : [
                  {
                     "formats" : {
                        "djvu" : {
                           "permission" : "open",
                           "url" : "http://www.archive.org/download/TheArtOfCommunity/TheArtOfCommunity.djvu"
                        },
                        "text" : {
                           "url" : "http://www.archive.org/download/TheArtOfCommunity/TheArtOfCommunity_djvu.txt"
                        },
                        "pdf" : {
                           "url" : "http://www.archive.org/download/TheArtOfCommunity/TheArtOfCommunity.pdf"
                        },
                        "epub" : {
                           "url" : "http://www.archive.org/download/TheArtOfCommunity/TheArtOfCommunity.epub"
                        }
                     },
                     "read_url" : "http://www.archive.org/stream/TheArtOfCommunity",
                     "availability" : "full",
                     "preview_url" : "http://www.archive.org/details/TheArtOfCommunity"
                  }
               ]
            },
            "details" : {
               "bib_key" : "isbn:9780596156718",
               "preview" : "full",
               "info_url" : "http://openlibrary.org/books/OL23747519M/The_Art_of_Community",
               "thumbnail_url" : "http://covers.openlibrary.org/b/id/6223071-S.jpg",
               "details" : {
                  "works" : [
                     {
                        "key" : "/works/OL15328717W"
                     }
                  ],
                  "number_of_pages" : 394,
                  "key" : "/books/OL23747519M",
                  "identifiers" : {},
                  "covers" : [
                     6223071
                  ],
                  "publish_date" : "August 2009",
                  "languages" : [
                     {
                        "key" : "/languages/eng"
                     }
                  ],
                  "isbn_10" : [
                     "0596156715"
                  ],
                  "publish_places" : [
                     "Sebastopol, California"
                  ],
                  "isbn_13" : [
                     "9780596156718"
                  ],
                  "authors" : [
                     {
                        "name" : "Jono Bacon",
                        "key" : "/authors/OL2654203A"
                     }
                  ],
                  "latest_revision" : 6,
                  "classifications" : {},
                  "pagination" : "xxv; 364",
                  "last_modified" : {
                     "value" : "2011-04-20T17:58:52.595370",
                     "type" : "/type/datetime"
                  },
                  "table_of_contents" : [
                     {
                        "level" : 0,
                        "label" : "1",
                        "type" : {
                           "key" : "/type/toc_item"
                        },
                        "title" : "The art of community",
                        "pagenum" : "1"
                     },
                     {
                        "level" : 0,
                        "label" : "2",
                        "type" : {
                           "key" : "/type/toc_item"
                        },
                        "title" : "Planning your community",
                        "pagenum" : "21"
                     },
                     {
                        "level" : 0,
                        "label" : "3",
                        "type" : {
                           "key" : "/type/toc_item"
                        },
                        "title" : "Communicating clearly",
                        "pagenum" : "65"
                     },
                     {
                        "level" : 0,
                        "label" : "4",
                        "type" : {
                           "key" : "/type/toc_item"
                        },
                        "title" : "Processes: simple is simple",
                        "pagenum" : "91"
                     },
                     {
                        "level" : 0,
                        "label" : "5",
                        "type" : {
                           "key" : "/type/toc_item"
                        },
                        "title" : "Supporting workflow with tools",
                        "pagenum" : "119"
                     },
                     {
                        "level" : 0,
                        "label" : "6",
                        "type" : {
                           "key" : "/type/toc_item"
                        },
                        "title" : "Building buzz",
                        "pagenum" : "145"
                     },
                     {
                        "level" : 0,
                        "label" : "7",
                        "type" : {
                           "key" : "/type/toc_item"
                        },
                        "title" : "Measuring community",
                        "pagenum" : "187"
                     },
                     {
                        "level" : 0,
                        "label" : "8",
                        "type" : {
                           "key" : "/type/toc_item"
                        },
                        "title" : "Governance",
                        "pagenum" : "211"
                     },
                     {
                        "level" : 0,
                        "label" : "9",
                        "type" : {
                           "key" : "/type/toc_item"
                        },
                        "title" : "Handling conflict",
                        "pagenum" : "267"
                     },
                     {
                        "level" : 0,
                        "label" : "10",
                        "type" : {
                           "key" : "/type/toc_item"
                        },
                        "title" : "Creating and running events",
                        "pagenum" : "301"
                     },
                     {
                        "level" : 0,
                        "label" : "11",
                        "type" : {
                           "key" : "/type/toc_item"
                        },
                        "title" : "Hiring a community manager",
                        "pagenum" : "341"
                     },
                     {
                        "level" : 0,
                        "title" : "Index",
                        "type" : {
                           "key" : "/type/toc_item"
                        },
                        "pagenum" : "359"
                     }
                  ],
                  "first_sentence" : "From ants to anteaters, bees to beekeepers, community is a fundamental part of our life on the planet.",
                  "created" : {
                     "value" : "2009-10-05T01:54:55.997126",
                     "type" : "/type/datetime"
                  },
                  "subtitle" : "Building the New Age of Participation",
                  "revision" : 6,
                  "notes" : "The author has made the PDF version of his book available under a CC-BY-SA-NC Creative Commons license.",
                  "publishers" : [
                     "O'Reilly Media, Inc"
                  ],
                  "title" : "The Art of Community",
                  "type" : {
                     "key" : "/type/edition"
                  },
                  "uris" : [
                     "http://artofcommunityonline.org"
                  ],
                  "ocaid" : "TheArtOfCommunity",
                  "contributions" : [
                     "Foreword by Leo Laporte"
                  ]
               },
               "preview_url" : "http://www.archive.org/details/TheArtOfCommunity"
            },
            "publishDates" : [
               "August 2009"
            ],
            "recordURL" : "http://openlibrary.org/books/OL23747519M",
            "oclcs" : [],
            "isbns" : [
               "0596156715",
               "9780596156718"
            ]
         }
      },
      "items" : [
         {
            "fromRecord" : "/books/OL23747519M",
            "enumcron" : false,
            "cover" : {
               "large" : "http://covers.openlibrary.org/b/id/6223071-L.jpg",
               "small" : "http://covers.openlibrary.org/b/id/6223071-S.jpg",
               "medium" : "http://covers.openlibrary.org/b/id/6223071-M.jpg"
            },
            "itemURL" : "http://www.archive.org/stream/TheArtOfCommunity",
            "ol-edition-id" : "OL23747519M",
            "status" : "full access",
            "match" : "exact",
            "ol-work-id" : "OL15328717W",
            "contributor" : "contributor"
         }
      ]
   }
}

JSONP support

For pure JavaScript usage, the JSONP convention is supported.

Append ?callback=<callback> and the data will be returned wrapped in a call to the function you specified in <callback>

curl http://openlibrary.org/api/volumes/brief/json/isbn:9780596156718?callback=parseMe

parseMe({
  "isbn:9780596156718":
    {"records": {...},
     "items": [...]
    }
});

Proxying requests for more borrowing, happier browsers

OpenLibrary Read API currently supports HTTP access only; modern browsers get angry if you include an HTTP resource in an HTTPS page
Borrowing partners of OpenLibrary are identified by IP address, so off-site users using JavaScript calls directly to OpenLibrary may be missing out on potential electronic borrowing options
Solution: proxy the OpenLibrary requests through your server
- Enables you to offer secure access and offer a consistent "Borrow" experience to your users
- Bonus: also avoids JavaScript same origin policy hassles
Don’t forget to proxy access to the borrowed resource as well!

Useful resources

Google Books v1 API
- Google API Console
- Documentation:
- google_books.py - Python script that demonstrates how to iterate over MARC records, find matching volumes by ISBN in Google Books, and add those volumes to a custom bookshelf
OpenLibrary Read API

Google Books and OpenLibrary APIs