GoogleBooks is a lightweight Ruby wrapper that queries the Google API to search for publications in the Google Books repository.
It is inspired by the google-book gem which relies on the deprecated Google GData Books API, but is updated to hook into the current Google API and expanded to provide additional methods and search options.
Using GoogleBooks is simple. There's just one class, GoogleBooks, and one method, search. Queries return an enumerable collection of results, each with their own set of attributes that can be individually configured.
require 'googlebooks' # unless you're using Bundler
books = GoogleBooks.search('The Great Gatsby')
first_book = books.first
first_book.authors #=> 'F. Scott Fitzgerald'
first_book.isbn #=> '9781443411080'
first_book.image_link(:zoom => 6) #=> 'http://bks2.books.google.com/books?id=...'
The search method allows for an options hash of up to four parameters. These parameters are page, count, order_by, and api_key. Necessity of a Google API key is application dependent; further information is available in Google's API documentation.
require 'googlebooks'
GoogleBooks.search('The Great Gatsby', {:count => 10})
#=> returns first ten results (default = 5)
GoogleBooks.search('The Great Gatsby', {:page => 2})
#=> returns second page of results (default = 1)
GoogleBooks.search('The Great Gatsby', {:count => 3, :page => 4, :api_key => 'THIS_IS_YOUR_API_KEY'})
#=> returns three results, beginning with the 10th overall result
By default, results are returned in order of relevance. However, results also be ordered from most recently to least recently published by passing newest to the order_by key. Passing anything other than newest will return results by relevance. Google does not currently support querying any values other than relevance and newest.
GoogleBooks.search('The Great Gatsby', {:order_by => 'newest'})
#=> returns results in order of most recently to least recently published
GoogleBooks.search('The Great Gatsby')
GoogleBooks.search('The Great Gatsby', {:order_by => `ANYTHING ELSE`})
#=> both return results in order of relevance
You can use the filter parameter to restrict the returned results further by setting it the to one of the following values:
partialReturns results where at least parts of the text are previewable.fullOnly returns results where all of the text is viewable.free-ebooksOnly returns results that are free Google eBooks.paid-ebooksOnly returns results that are Google eBooks with a price.ebooksOnly 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.
Examples:
GoogleBooks.search('ruby', :filter => 'free-ebooks')
Some users may experience issues when querying the Google API from IP addresses that cannot be geolocated by Google. From this Google forum:
Unfortunately the Books API cannot return any results for IPs that we cannot geo-locate. This is due to both legal and contractual reasons. Google does not have the rights to display all the books in all countries. Even public domain laws vary by country.
Users experiencing issues can typically resolve this limitation by passing a valid country code to the country parameter in the URL query.
GoogleBooks.search('The Great Gatsby')
#=> "Cannot determine user location for geographically restricted operation."
GoogleBooks.search('The Great Gatsby', {:country => "ca"})
#=> returns the first five results
There are special keywords you can specify in the search terms to search in particular fields, such as:
intitleReturns results where the text following this keyword is found in the title.inauthorReturns results where the text following this keyword is found in the author.inpublisherReturns results where the text following this keyword is found in the publisher.subjectReturns results where the text following this keyword is listed in the category list of the volume.isbnReturns results where the text following this keyword is the ISBN number.
Examples:
require 'googlebooks'
books = GoogleBooks.search('isbn:9781443411080') # yields a collection of one result
book = books.first # the one result
book.title #=> 'The Great Gatsby'
By default, GoogleBooks can query the following attributes (note that not all attributes are available to all books):
titletitles_array*Returns an array of all titles, both main and alternativeauthorsReturns all authors as a comma delimited stringauthors_array*Returns an array of all author namespublisherpublished_datedescriptionisbnAttempts to return 13-digit first, then 10-digit, then nilisbn_10Returns 10-digit form onlyisbn_13Returns 13-digit form onlypage_countprint_typecategoriesReturns all categories as a comma delimited stringaverage_ratingratings_countlanguagepreview_linkinfo_linkimage_linkSee details below
Sale and retail information is available on some volumes as of Google Books API v1. GoogleBooks returns a hash of these attributes (where available) under the sale_info attribute.
book = GoogleBooks.search(9780345508553).first # Do Androids Dream of Electric Sheep?
book.sale_info['country'] #=> 'US'
book.sale_info['saleability'] #=> 'FOR_SALE'
book.sale_info['isEbook'] #=> true
book.sale_info['listPrice']['amount'] #=> 9.99
book.sale_info['listPrice']['currencyCode'] #=> 'USD'
book.sale_info['retailPrice']['amount'] #=> 9.99
book.sale_info['retailPrice']['currencyCode'] #=> 'USD'
book.sale_info['buyLink'] #=> 'http://books.google.com/books?id=jUX8N9kiCiQC&dq=9780345508553&buy=&source=gbs_api'
Note that the sale_info attribute is only available for some volumes and will sometimes return nil for nested attributes. Use with caution as GoogleBooks does not provide built-in error handling for instances of nil.
When possible, GoogleBooks will return links to an image of a book's cover. The size and appearance of the cover can be configured by passing an optional hash of arguments to the attribute.
The size of this image is configurable by passing an numerical argument between 1-6 to the image_link attribute, which is passed to the zoom attribute in the URL query.
:zoomPass numeric value between 1-6 to the zoom attribute (default = 1)
GoogleBooks will, by default, return the image_link for an aesthetically unmodified cover. However, if you'd like Google to return an image with a "curled" corner (when available), you can pass true to this key.
:curlPass true to return image_link of cover with curled corner (default = false)
Examples:
book = GoogleBooks.search("The Great Gatsby").first
# return image_link with default options
book.image_link # zoom=1, edge=none
# return image_link of varying sizes
book.image_link # small
book.image_link(:zoom => 5) # thumbnail
book.image_link(:zoom => 2) # medium
book.image_link(:zoom => 3) # large
book.image_link(:zoom => 4) # extra large
# return image_link with curled corners
book.image_link(:curl => true)
# return thumbnail image_link with curled corners
book.image_link(:zoom => 5, :curl => true)
The current Google API for Books generally requires that the requesting server's IP address be geolocatable. This can cause responses to be restricted when requested from distributed/clustered servers such as Heroku.
GoogleBooks can resolve these issues by adding an X-Forwarded-For HTTP header to each request that contains the IP address of the user. In most cases, you can pass the user's IP address as the third parameter in your search request:
# Request made from Heroku server without passing user's IP address to HTTP header
GoogleBooks.search("Search Query", {options_hash}) #=> returns error hash
# Request made from Heroku server with user's IP address
user_ip = request.remote_ip # assuming user is accessing from a valid IP address
GoogleBooks.search("Search Query", {options_hash}, user_ip) #=> returns valid hash of results
Doing this will, for the most part, enable you to query the Google API from apps that reside across distributed nodes.
GoogleBooks is licensed under the GNU GPL. Modify and distribute freely.
Please feel free to contact the developer with any questions or suggestions. Forking and merge/pull requests are encouraged for those who would like to take part in improving this gem.