HomeGroupsTalkZeitgeist

LibraryThing JSON Books API

From WikiThing

Jump to: navigation, search

<< back to Help and Frequently Asked Questions

This is a Help or FAQ page

Please answer LibraryThing related questions here (and on the other Help and FAQ pages). To ASK questions, however, please use Talk.

Contents


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.

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.

API Documentation

Basic use

Advanced use

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

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.
  • showTags. =1 to include tags when available.
  • showCollections. =1 to include collection membership information.
  • 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.
  • responseType. Optional.
    • json returns a raw JSON data sctructure.
    • Default returns a javascript block with the data in a variable.

Data Returned

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?

Result set: ratings

  • rating : rating of book. 0 is unrated.

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)

Result set: booktags

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

Examples

Note the URL to see the parameters in use.

You are using the new servers! | About | Privacy/Terms | Help/FAQs | Blog | Store | APIs | TinyCat | Legacy Libraries | Early Reviewers | Common Knowledge | 113,213,871 books! | Top bar: Always visible