Tuesday, March 25, 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: , ,

12 Comments:

Blogger Gary McGath said...

Looks useful! I had trouble getting it to work till I figured out that the script had to be after the DIV and SPAN tags that used it.

I tried to get it to work on LiveJournal, but couldn't, probably because they filter out third-party Javascript (which is sensible).

3/25/2008 4:23 PM  
Blogger Tim said...

Oh, good point. Yeah, it should be at the bottom of the page. I'll add that.

LiveJournal filters out all JS. See http://www.librarything.com/blog/2006/12/graphical-widgets-for-lj-and-etc-first.php for our lame soluton.

3/25/2008 4:24 PM  
Anonymous Anonymous said...

The hash is sent to a function of your choosing, or the simple LT_addLibraryThinglinks by default.

How do I do that choosing?

3/25/2008 6:06 PM  
Blogger Tim said...

Sorry add &callback=FUNCTIONNAME to the URL.

T

3/25/2008 8:38 PM  
Blogger Kent said...

Thanks, works well:
sample search on NLA Library Labs

3/25/2008 11:32 PM  
Blogger Tim said...

Oh, I should explain that the "rating" is twice what is displayed. That is ratings are 0-5 stars, with halves. So I use 0-10 stars.

3/26/2008 12:32 AM  
Anonymous Anonymous said...

Are there different parameters you can pass? I want to implement your tagging system too, but I can't figure out how. Is it part of this API or another one?

thanks

3/26/2008 1:32 PM  
Blogger Tim said...

No free tagging API. We sell tagging—and book recommendations—through LibraryThing for Libraries. See /forlibraries.

3/26/2008 2:05 PM  
Blogger Mark Watkins said...

Perhaps I am missing something obvious - but - is there any way to programatically access my library? (in particular I'd love to get back a JSON list of all my books with a particular tag, that I could manipulate). But I don't see a way to use this or any other LT api to do so...I suppose I could automate an export & filter, but that seems clumsy...

5/11/2008 4:59 PM  
Blogger Sidney A said...

I was able to get it to work EXACTLY like Google Book's Search API, as a matter of fact I just integrated it directly into their code. All I did was append this at the end of the scriptURL
&callback=var%2520_ProcessLBTBookInfo%2520%253D%2520
It basically parses out to
var _ProcessLBTBookInfo =
Hope this helps someone out.

5/19/2008 4:19 PM  
Blogger Fredrik Wendt said...

Any progress on releasing a public API? Will use goggle for book covers but they don't provide a title for the books and was hoping TL could be used for this.
Intended use is to have the dev group's books in a list where we all can see who has which book (something LT can't help us with - otherwise we'd just use that).

5/31/2008 3:40 AM  
Blogger Fredrik Wendt said...

Ouch - just replaced athena with www in the URL. :)

5/31/2008 3:50 AM  

Post a Comment

<< Home