21 June 2010

Which book API to use for a mobile book app? (Part II)

(...continued from Part I...)

Here is an evaluation of the various Book APIs available with regard to their suitability for use in a standalone Android application. Please see Part I for more background information - this post contains just the raw evaluation and conclusions.

Amazon

Previously called "eCommerce Service API" (or ECS), Amazon's Product Advertising API is part of the Amazon Web Services (AWS), although the correct link is challenging to find if you start from the top AWS link.

Developer Guide

Access
Provides basic Item Search/Lookup and List Search/Lookup. Lists aren't exactly the same a bookshelves, but I suppose that they're close enough.

Read/Write
As far as I can tell in the API, there is no way to add a new list or add an item to an existing list. You can, of course, edit/modify the shopping cart, so write access is provided by the API. It seems that Amazon wants the API to be read-only unless you're trying to buy something.

Auth
Each app that wants to use the API needs to register for an AWSAccessKeyId and then use that ID in all requests.

I didn't investigate how one would access non-public lists using this API. Presumably this would require some further authentication, but the API restrictions made me stop evaluating.

Restrictions
From the license agreement, the purpose of the API is to "permit you to advertise items offered on the Amazon Site". Each app that wants to use the API requires enrollment and approval by Amazon (it's apparently not an automated process).

The license mentions that
Unsuitable applications include those that:
(a) do not have as their principal purpose advertising and marketing the Amazon Site and driving sales of products and services on the Amazon Site;
!!

Conclusion
Given the access limitations and the license requirements, this API does not seem suitable for use for this purpose. It might be worth considering in the future if I want to extend this app by adding a link to an Amazon page.

aNobii

aNobii API Home

Access
aNobii has 3 API calls: item.getInfo, shelf.getSimpleShelf and contributor.getInfo.

These seem like they would be enough for a basic read API, but I was unable to get them to work correctly (I kept getting getting a code 401 "Missing parameter(s)" error - was my api_key wrong or was I passing the wrong book id, I have no idea).

Read/Write
Read-only.

Auth
Requires a devkey with an extra "secret" id that you combine and then run through a MD5 hash to create your real API key.

Restrictions
The terms of service include the following:
b. You shall not:
Use aNobii APIs for any application that replicates or attempts to replace the essential user experience of aNobii.com.
Since I'm sure a mobile book management app could easily be construed as replacing the "essential user experience" of aNobii.com, it's probably
not valid to use the API for this.

Conclusion
As with all of the APIs that require a devkey, there is an issue with assigning a devkey to an application that is distributed (like a phone app). Even though each app is run by a separate user, they all are counted toward the same app id.

Perhaps this would work if each user could get easily get their own developer key + private key. The user would enter this info once when they installed the app.

In any case, since this is read-only (and didn't seem to work properly for me), I'll probably pass on this for now since the APIs provided by other sources provide more functionality.

GoodReads

Access
Nice API with access to most things that you could want. Book info, shelf info for a user, list of books in a shelf.

Examples:
  • Get a list of shelves:
    http://www.goodreads.com/shelf/list?format=xml&v=2&key=<devkey>&user_id=<id>

  • Get list of books in shelf:
    http://www.goodreads.com/review/list?format=xml&v=2&key=<devkey>&id=<id>&shelf=<shelf-name>
Read/Write
Both reads and writes are supported. Writes require authentication.

Auth
Most API calls require either a devkey or require that a user be authorized via OAuth.

Restrictions
License is pretty standard. API queries are limited to no more than 1 query/second.

Conclusion
GoodReads has a well thought-out API and handles authorization properly. The only concern is that some are OAuth-based while others are devkey based. Since the devkey based accesses are limited to 1 query/second, this may be a problem when incorporating calls into a standalone app (since the app would be installed on lots of different end-user devices).

However, this definitely seems like something worth pursuing.

Google Books

Google Book Search API - Getting Started Guide
Google Book Search Data API : Developer's Guide

Access
Basic book info and shelves (with shelf editing) are supported.

Read/Write
Book data can be read and user shelf info can be read/written (with authentication).

Auth
General book queries don't require authorization, but to access user-specific data (like bookshelves) it is necessary to have the user authenticate. All writes also require authentication.

Since the Google Books data is exposed using the Google Data protocol, this authentication can be done using either AuthSub, OAuth or ClientLogin, as described in the Google Data Authentication page.

Restrictions
The Terms of Service are long and "legal" and deal mostly with requiring that you don't misrepresent yourself (or your app), that you respect Google trademarks and the privacy of the users and that you abide by all applicable laws. Most of it seems pretty boilerplate for a web service.

No queries/second restrictions, although I suspect if your app started DoSing the service it would get cut off rather quickly.

The only item that stood out is that Google reserves the right to insert advertising in the content. This isn't the case with any of the Google Books APIs that I've ever used and I'm not sure how that would work when using a simple text-based API. In any case, this doesn't seem to be an issue but it's worth being aware of.

Conclusion
In order to securely access user data (like bookshelf info), having a system that allows the end-user (rather than the app developer) provide credentials is essential. This is one of the few APIs that supports this.

ISBNdb

Developer API

ISBNdb crawls various libraries to build/maintain a database of ISBNs.

Access
Only provides basic ISBN book lookup.

Example:
http://isbndb.com/api/books.xml?access_key=<key>&index1=isbn&value1=<isbn>
Read/Write
Read-only.

Auth
Dev key required to access.

Restrictions
None mentioned on site.

Conclusion
Not worth investigating further for this application since this info seems readily available elsewhere with fewer restrictions.

LibraryThing

LibraryThing APIs

LibraryThing has a collection of different APIs rather than one coherent API. They are divided into 4 basic categories: Covers, JSON, Webservices, and Misc.

Covers
  • Used to get book covers given an ISBN.
  • Requires a devkey and is limited to 1000 queries/day
JSON APIs
  • Books API
    • This allows you to lookup a book on LibraryThing.
    • The Books API page shows 2 different example formats:
      • http://www.librarything.com/api/json_books.php?userid=<user-id>&key=<key>&showstructure=1
      • http://www.librarything.com/api_getdata.php?userid=<user-id>&key=<key>&showstructure=1
    • They both return basically the same info, but the "json_books" version includes a bunch of widget-creating JavaScript at the top before the data begins.

  • Works (book search) API
    • This is a book search API and the only documentation relating to it is in this blog post
    • This doesn't require a developer key.
WebServices APIs
  • This appears to be a work-in-progress since it only provides access to a LibraryThing works and authors. I didn't see way to access user lists.
  • This requires an apikey and is limited to 1000 queries/day.
  • Example:
    • http://www.librarything.com/services/rest/1.0/?method=librarything.ck.getwork&apikey=<apikey>&id=<librarything-id>
Misc APIs
  • Easy Linking: Link to LibraryThing using ISBN (rather than LibraryThing book id).
  • ThingISBN: given an ISBN, return a list of related ISBNs
  • ISBN -> LibraryThing book id
  • ISBN -> book language
  • ISBN validate
  • Title -> list of possible ISBNs

Access
These APIs provide basic access to book data. However, none of the APIs appears to provide access to the user collections. Shelf functionality could be re-created using the tags (which are available in the API), but it seems odd not to use LibraryThing's native "shelf" concept

Read/Write
Mostly read access but write access of sort-of there. You can add a book using:
http://www.librarything.com/addbook/<isbn>
But this assumes that you are already logged in, so it doesn't really work for a standalone app.

Auth
Devkeys are required for the JSON and WebServices API calls (although different keys are needed for each). No real Authentication is provided to access user data.

Restrictions
Most API calls require a devkey and they're all limited to 1000 queries/day.

Some of the license requirements are quite odd. For example, the JSON Books API actually says the following:
We have yet to settle on a license. You agree to abide by whatever license we eventually choose.
!!

In addition, both of the JSON APIs have the following in the license:
Must be run as Javascript on user's browser, not fetched by a server; cannot be stored, except for browser caching. Commercial use requires a hard (non-JS) link to LibraryThing on every page that returns results.
Which is clearly not the case if I want to run call this from a phone app.

Conclusion
Overall, while there are many things to like about what LibraryThing provides, there are too many parts that don't seem mature enough to support a phone app based on the current APIs. In addition, the licensing requirements for some of the APIs are best described as quirky and certainly preclude creating things like phone apps.

Still, I was left with the impression that there's some useful stuff here and it might be useful to add some sort of LibraryThing integration.

OpenLibrary

OpenLibrary APIs:
REST API
Books API
Covers API

Access
Basic access to books. E.g., using:
http://openlibrary.org/api/books?bibkeys=ISBN:<isbn>&details=true
No access to lists since it's a new feature that they're still working on.

Read/Write
Read only.

Auth
OpenLibrary allows you to login automatically by POSTing to http://openlibrary.org/account/login. This sets a login cookie and is apparently intended for web access.

The API doesn't have or require authentication.

Restrictions
None mentioned on the site.

Conclusion
Issues:
  • Lack of support for lists
  • Lack of write support
Not worth investigating further for this application.

WorldCat

WorldCat Search API
WorldCat Basic API

Access
Provides basic access to books, but doesn't appear to allow access to user created lists.

Read/Write
Read-only.

Auth
Requires a devkey for all access

For example to do a simple lookup by ISBN:
http://www.worldcat.org/webservices/catalog/content/isbn/<isbn>?wskey=<key>
where <key> is your assigned key.

Restrictions
Limited to 1000 queries per day.

Conclusion
Issues:
  • Devkey + query limit make this inappropriate for an app unless each user gets their own devkey
  • Lack of access to user created lists
  • Lack of write functionality
Not worth investigating further for this application.



Whew! I'm glad that's done. Please let me know if you see any errors or omissions.

I need to say that I'm actually a bit surprised that more APIs didn't make the cut and with how critical the Auth problem ended up being. I was also kinda hoping that LibraryThing would do better than it did.

But now it's time to start playing more with the 2 finalists (GoodReads and Google Books) to see how well they work in practice. Perhaps I'll experiment a bit more with LibraryThing as well.

1 comment:

Mike C said...

Gary,

Many, many thanks for this - I am searching for an API to get information and reviews of books that I can re-use on my eCommerce site to sell second-hand Books (and DVDs, CD's and LPs) so this article saved me weeks of work!

The best one in my opinion is the Amazon web services but of course you can't reuse the information so the next best seems to be GoodReads for me.

Anyway, I'd be interested to know which service you opted for in the end and did it allow you to create the app you wanted?

Cheers,

Mike