LibraryThing APIs

From WikiThing

Jump to: navigation, search

What's an API?

APIs are ways for one computer to talk to another, simple ways of getting and giving data without having to share programming code.

See Wikipedia.

For tab-delimited and CSV exports of your library see the Tools tab. For our RSS feeds see here.


The Developer Key

A few of the LibraryThing APIs require a LibraryThing Developer Key. See each API for details. If you need a key, go ahead and get one. The LibraryThing Developer Key has its own Terms and Conditions.

Easy Linking

You can link to a work page on LibraryThing just by throwing the ISBN into the URL.

You can also link to a book by putting the book's title in the URL. Spaces can be represented by underscores, + signs, or even simply as spaces (more here).

You can add books to your account as follows. If you aren't logged in, it will go to the work page.

APIs (Application Programming Interfaces)

1. JSON Books API

See LibraryThing JSON Books API

  • 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.
  • Developer key: Not needed.

2. JSON Works API

See http://blog.librarything.com/thingology/2008/03/first-cut-works-json-api/

  • 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.
  • Developer key: Not needed.

3. ThingISBN

ThingISBN takes an ISBN and returns a list of "related" ISBNs—ISBNs from the same "work" (i.e. other editions and translations).

4. What Work?

"What work?" takes an ISBN and/or a title-author and returns the LibraryThing work number.

  • See the blog post
  • License: Free to all with attribution (see below)

5. ThingLang

ThingLang takes an ISBN and returns the language of the book.

  • ThingLang uses language codes from MARC records and from the Group Identifiers embedded at the start of the ISBN format.
  • Results are in the form of a three letter MARC language code
  • Read the announcement, with examples and details.
  • License: Unrestricted (see below); hit it no more than 1/second
  • Developer key: Not needed.

6. ISBN Check

Takes an ISBN; validates it and returns the ISBN10 and ISBN13 form.

  • Under no conditions may you call this "ThingISBNCheck"
  • See announcement
  • License: Unrestricted (see below); hit it no more than 10/second
  • Developer key: Not needed.

7. ThingTitle

ThingTitle takes a title and returns a list ISBNs from the most likely LibraryThing "work," the LibraryThing title and a link to the LibraryThing work page.

  • Announcement, with examples
  • License: Non-commercial use (see below)
  • Developer key: Not needed.

8. Add Events

Adds events to the LibraryThing Local events system using a simple "RESTful" API.

  • API page, with examples
  • Developer key required

Data feeds

Feeds are available here: http://www.librarything.com/feeds/

1. ThingISBN

  • A feed version of the above API.
  • License: Non-commercial use (see below)

2. AllLibraryThingISBNs

  • A simple list of all ISBNs in LibraryThing.
  • License: Non-commercial use (see below)

3. WikipediaCitations

  • A list of ISBNs to Wikipedia articles (described on the blog).
  • License: Non-commercial use (see below)

4. Add Events API The Add Events API adds events to the LibraryThing Local events system using a simple "RESTful" API.

Each Add Events request consists of a single http request, with all parameters specified in the URL. There is no ganging of requests.


Basic fields

title. The title of the event.

time. The date and time of the event, preferably in the format YYYY-MM-DD HH:MM (eg., 2012-12-01 14:00).

Ideally the HH:MM should be in 24-hour (or "military") format, although you can also append "AM" or "PM." All times should be local time; not include timezone data, or it will throw off the time calculation as it attempts to square it with LibraryThing's timezone.

description. The description of the event. Works and authors should NOT be touchstones in the description.

isbns. A comma-separated list of ISBNs relevant to the entry. LibraryThing uses these to retrieve all potential work titles and author names implicated in the description, and creates touchstones as appropriate.

ISBNs are not only for works, but also for authors. For example, if an author is delivering a talk but not reading from any specific work, referencing one of their ISBNs will still ensure that their name in the description gets turned into a touchstone.

eventurl. URL of the event at the venue's website.

mediaurl. Archived media of the event (for past events only).

Finding the venue

There are two ways of finding the venue:

venue. If you know the LibraryThing venue id, use the venue= parameter.

The LibraryThing venue id is located in venue URLs. For example, <a href="http://www.librarything.com/venue/924/Strand-Bookstore">http://www.librarything.com/venue/924/Strand-Bookstore</a> has the venue id 924.

venuesearchtype, venuesearchdata and venuesearchexact. Using these two parameters you instruct LibraryThing to search for a venue. If exactly one venue is found, it will go ahead and choose it, and add the event. There are X venuesearchtype options.

phone. Searches the venue's phone number. All non-numbers are ignored (ie., 207-555-1212 is the same as 207.555.1212, etc.).

twitter. Searches the venue's Twitter handle, if they have one.

email. Searches for the email.

name. Searches the venue name.

venuesearchdata is the search string.

venuesearchexact is whether to do match on partial searches (ie., "Strand" matching "Strand Bookstore," "Strand Book Annex," "The Strand Bookshop," etc.).

Your information

userid. Your LibraryThing userid (ie., timspalding).

developerkey. Developer key. This can be found at http://www.librarything.com/services/keys.php . If you are not a registered developer, you can sign up and get your developer key in less than a minute.

Making it happen

addevent. To make it add the event, rather than just test the system and see an XML response, set addevent=1.

Terms of Use

  • By using any of LibraryThing's APIs you agree to these terms of use.
  • "Non-commercial" restricts the data to non-commercial use only; commercial use requires our written permission.
  • "Unrestricted" data can be used for both non-commercial and commercial use.
  • "Free to all with attribution" means anyone can use the API, but must provide attribution and a link, either to the work in question or to LibraryThing.com.
  • Except for ISBN Check, you can make only one request per second on an API; if you're going to hit it more than 1,000 times/day, you must notify LibraryThing
  • APIs are provided "as is," without any promises or guarantees of any sort. You're on your own!
  • We reserve the right to change these terms and generally make things up as we go along.
You are using the new servers! | About | Privacy/Terms | Help/FAQs | Blog | Store | APIs | TinyCat | Legacy Libraries | Early Reviewers | Common Knowledge | 118,007,390 books! | Top bar: Always visible