From WikiThing

<<back to Help and Frequently Asked Questions

[edit] Intro

The JSON Books API provides data about a member's personal library. It is the data source behind our widgets, which can be seen here. The API can also be used directly to retrieve an array of book data.

[edit] License

• We have yet to settle on a license. You agree to abide by whatever license we eventually choose.
• We are looking for a license that requires that all software built to process the JSON Books API be open source, so members can build on each other's work. The LT software that produces the API is not be open-sourced, but all the JS we're writing to process it is.
• The license should not impact the data one way or another.

[edit] API Documentation

[edit] Basic use

• Use the widget building page.

[edit] Advanced use

• Use www.librarything.com/api_getdata.php with the following parameters to receive data from the API.

[edit] URL parameters

• userid. Required. Your user name
• key. Required. Every user has a unique "key" access their JSON books API; see http://www.librarything.com/api/json.php for your key. The key prevents you from misusing others data—and, frankly, from harvesting 30 million books from us. Note that this key is not the same as the web services API key. Go to the web page above to see what your key will be.
• resultsets. Optional. Default is "books,ratings"
  • bookratings : your ratings
  • bookreviews : your reviews
  • bookdate : acquired, starting, ending dates
  • booktags : your tags
• coverheight. Intended cover height. Optional. Default is 100.
• coverwidth. Intended cover width. Optional. Default is NULL, which means the height is used exclusively.
• booksort. Optional. Default is "random"
  • random : random
  • entry : entry order
  • entry_REV : reverse entry order
  • title : title order (a-z)
  • title_REV : reverse title (z-a)
  • author : author order
  • author_REV : reverse author order
• max. Maximum number of books returned. Default is 20.
• reviewmax. Maximum length (in characters) of reviews returned. Default is 100.
• showstructure. Optional. default is 0. If set to 1, JavaScript includes a comment that shows the array structure of the data (http://www.librarything.com/api/json_books.php?userid=timspalding&key=4200869464&showstructure=1)
• callback. What function should be called with the JSON data. Optional. Default is LT_API_dowidget()—from the standard library.
  • reviewsOnly. Only return books with reviews
  • showReviews. =1 to include reviews when available.
  • bookswithstartorfinishdates : only books with start or finished dates
• libraries. Optional. Default is "standard"
  • standard : a set of standard functions for adding book titles, etc.
  • tagList : Comma delimited list of tags. This is an additive list. "bone, comics" will return books with either tag, not just books that have both tags.

[edit] Data Returned

[edit] Result set: books

• book_id : The unique id of every book
• title : The title of your book
• author_lf : Author (last, first)
• author_fl : Author (first, last)
• author_code : The author code that gets the author page, eg., twainmark produces the author URL http://www.librarything.com/author/twainmark
• ISBN : Book's ISBN as entered
• ISBN_cleaned : Book's ISBN with extraneous dashes and other data removed, converted to a 10-digit ISBN if a 13-digit 978-based ISBN. Omitted if the ISBN is not valid.
• publicationdate : The publication date, as entered
• entry_stamp : Unix timestamp of entry
• entry_date : The date of entry (US format)
• copies : The "copies" field, as entered
• language_main : main language
• language_secondary : secondary language
• language_original : original language
• hasreview : Does the book have a review?

[edit] Result set: ratings

• rating : rating of book. 0 is unrated.

[edit] Result set: bookreviews

• bookreview : the review itself, limited by reviewmax (above)
• bookreview_stamp : Unix timestamp of review date
• bookreview_date : Date of review (US format)

[edit] Result set: booktags

• tags : an array of all tags per book, in display order

[edit] Example

Click here to see an example. http://www.librarything.com/api_getdata.php?userid=LibrarythingLuke&showstructure=1&limit=3&showTags=1&booksort=title_REV&tagList=twitter Note the URL to see the parameters in use.