Tuesday, March 25th, 2008

First cut: Works JSON API

I’ve finished a simple Javascript/JSON API to LibraryThing’s core work information. In structure and implementation the API resembles Google’s recent Book Search API, but for LibraryThing.

Purpose. The API is designed to help libraries and others to add links to LibraryThing when LibraryThing has a book, and omit them when we don’t. It’s an easy conditional-linking system.

But the API returns other work information too, including the number of copies, number of reviews and average rating (with rating image). It comes with a simple function to insert the data where appropriate, but you can funnel this information to functions of your own devising.

Scope. This is an API to work information. Once I’ve worked through the kinks here, I plan to release a member API, allowing members to do clever things with their data. For example, members will be able to make their own widgets, not just rely on ours.

How it works. The basic mode of operation is to insert a script as follows:

<script src="http://www.librarything.com/api/json/workinfo.js?ids=*******"></script>

The ******* is reserved for the ISBNs you want to look up on LibraryThing, separated by commas. NOTE: This script should be placed at the bottom of the page.

For example, the JSON API Test includes one ISBN-10, one ISBN-13, one LCCN and one OCLC number.

<script src="http://www.librarything.com/api/json/workinfo.js?ids=0066212898,9780520042728,99030698,ocn8474750911"></script>

The script returns a hunk of JavaScript, including both the simple function and the JSON hash with all the book data. The hash is sent to a function of your choosing, or the simple LT_addLibraryThinglinks by default. To name another callback function add &callback= and the function name to the URL.

The function LT_addLibraryThinglinks looks for elements (DIVs, SPANs, etc.) with the ID “LT_xxx” where xxx is one of your identifiers. If LibraryThing has a work, it adds “(See on LibraryThing)”, with link. If not, it does nothing.

Here’s the JavaScript returned for the URL above:

LT_addLibraryThinglinks(
{
"0066212898":
{"id":"0066212898","type":"isbn","work":"3702986","link":"http://www.librarything.com/work/3702986","copies":"105","reviews":"7","rating":8.33,"rating_img":"http://www.librarything.com/pics/ss8.gif"},
"9780520042728":
{"id":"9780520042728","type":"isbn","work":"44723","link":"http://www.librarything.com/work/44723","copies":"92","reviews":"3","rating":8.47,"rating_img":"http://www.librarything.com/pics/ss8.gif"},
"99030698":
{"id":"99030698","type":"lccn","work":"32155","link":"http://www.librarything.com/work/32155","copies":"345","reviews":"10","rating":7.8,"rating_img":"http://www.librarything.com/pics/ss8.gif"},
"ocn8474750911":
{"id":"ocn8474750911","type":"oclc","work":"4161224","link":"http://www.librarything.com/work/4161224","copies":"1","reviews":"0","rating":0,"rating_img":""}}
);

More later. It’s 2:48am and need to get to bed. There’s much more to say, of course.

Labels: apis, javascript, JSON

2 Comments:

  1. This helped me to accomplish my work with ease 🙂