Library Lookup Web Service

This service is currently limited to libraries in London, United Kingdom.

Background

The main purpose of this service is to provide access to a database of public libraries in the UK. In addition, the service is able to check if a book (identified by its ISBN) is available at supported libraries.

Results can be retrieved in 2 representation formats: XHTML or JSON. XHTML is returned by default and contains microformatted data (XOXO, hCards, geo).

The service allows you to retrieve:

a list of libraries based on ID, name or location
availability of books held by libraries

Retrieving a list of libraries

All requests for libraries will return a maximum of 20 results, even if there are more libraries matching the request.

Request

By location

To get a list of libraries near a location, you can either provide a UK postcode or the latitude and longitude values:

Postcode template	http://librarylookup.org.uk/v1/libraries/near={postcode}
Lat,Lon template	http://librarylookup.org.uk/v1/libraries/near={lat},{lon}
Postcode example	http://librarylookup.org.uk/v1/libraries/near=W6+0QL
Lat,Lon example	http://librarylookup.org.uk/v1/libraries/near=51.49,-0.22

Results will only be returned if there are matches within roughly a 15 mile radius.

By name

To find a library by name, you should provide all or part of the name:

Template	http://librarylookup.org.uk/v1/libraries/name={name-of-library}
Example	http://librarylookup.org.uk/v1/libraries/name=kens

By ID

If you know the unique ID number of the library (e.g. from a previous request) you can retrieve details of that library as follows

Template	http://librarylookup.org.uk/v1/libraries/{id}
Example	http://librarylookup.org.uk/v1/libraries/158

To retrieve details of more than one library, you can supply multiple IDs (up to a maximum of 20) by separating each one with a semicolon:

Template	http://librarylookup.org.uk/v1/libraries/{id};{id};{id}...
Example	http://librarylookup.org.uk/v1/libraries/158;1;30

Representation formats

The examples above all return XHTML responses. The service can also return JSON and JSON wrapped inside a callback function:

JSON	Add .json to the end of the URL
JSON + callback	Add .json?callback=functionName to the end of the URL
Example 1	http://librarylookup.org.uk/v1/libraries/near=N7+0SF.json
Example 2	http://librarylookup.org.uk/v1/libraries/near=N7+0SF.json?callback=functionName

Arguments

The service accepts the following arguments passed in the query string:

Argument	Description	Example URL
count	maximum number of results to return	http://librarylookup.org.uk/v1/libraries/near=W6+0QL?count=3
callback	function to call with JSON data	http://librarylookup.org.uk/v1/libraries/near=W6+0QL.json?callback=myFunction

Response

HTTP status codes

The following HTTP status codes may be returned in response to requests:

200	OK: no problems encountered
400	Error: the request was not understood
404	Error: a requested library was not found (invalid ID supplied)

HTTP content type

The value of the HTTP Content-Type header depends on the representation format requested:

Format	Content-Type	Example URL
XHTML	text/html	http://librarylookup.org.uk/v1/libraries/near=W6+0QL
JSON	application/json	http://librarylookup.org.uk/v1/libraries/near=W6+0QL.json
JSON + callback	text/javascript	http://librarylookup.org.uk/v1/libraries/near=W6+0QL.json?callback=myFunction

Body

The response to the the requests listed above is a set of key-value pairs. The list below describes some of the values to expect. Areas with a grey background indicate keys which are not always present in the response.

status

'ok' or 'error'

error

only present when status is 'error'

message: error message

type

'library' when the request is for a single library (one library ID supplied), 'libraries' otherwise

url_templates

list of URL templates that can be used to for making further requests

near

only present when request is for libraries near a given location

postal-code: postcode if request asked for libraries near a postcode
latitude: latitude if request asked for libraries near a lat/lng point
longitude: longitude if request asked for libraries near a lat/lng point

results

list of matching libraries, each with the following key-value pairs

id

library ID

title

library name

url

local URL identifying library

supported

'yes' if library can be checked for book availability, 'no' otherwise

distance

only present when request is for libraries near a given location

miles: distance from given location in miles
kilometres: distance from given location in kilometres

url_templates

list of URL templates that can be used to for making further requests involving this library

vcard

library contact details according to hCard (for XHTML output) or jCard (for JSON output) specs

fn: library name
org: library name
adr: library's address (currently only postal-code and country-name)
geo: library's geographic coordinates (latitude and longitude)

Example JSON output

{"status":"ok",
 "type":"libraries",
 "url_templates":
    {"check_availability_within_top_5_results":"/v1/availability/near=W6+0QL/by-isbn/{isbn}.json",
     "list_libraries_near_postcode":"/v1/libraries/near={postcode}.json"},
 "near":
    {"postal-code":"W6 0QL"},
 "results":[
    {"id":"158",
     "title":"Hammersmith Library",
     "url":"/v1/libraries/158.json",
     "supported":"yes",
     "distance":
        {"miles":0.18,
         "kilometres":0.29},
     "url_templates":
        {"check_availability":"/v1/availability/158/by-isbn/{isbn}.json"},
     "vcard":
        {"fn":"Hammersmith Library",
         "org":"Hammersmith Library",
         "adr":
            {"postal-code":"W6 7AT",
             "country-name":"United Kingdom"},
         "geo":
            {"latitude":"51.494529",
             "longitude":"-0.223672"}}},
    {"id":"154",
     "title":"Archives and Local History Library",
     "url":"/v1/libraries/154.json",
     "supported":"no",
     "distance":
        {"miles":0.33,
         "kilometres":0.53},
     "url_templates":
        {},"vcard":
        {"fn":"Archives and Local History Library",
         "org":"Archives and Local History Library",
         "adr":
            {"postal-code":"W6 8BJ",
             "country-name":"United Kingdom"},
         "geo":
            {"latitude":"51.490734",
             "longitude":"-0.220103"}}},
    {"id":"160",
     "title":"Shepherds Bush Library",
     "url":"/v1/libraries/160.json",
     "supported":"yes",
     "distance":
        {"miles":0.84,
         "kilometres":1.36},
     "url_templates":
        {"check_availability":"/v1/availability/160/by-isbn/{isbn}.json"},
     "vcard":
        {"fn":"Shepherds Bush Library",
         "org":"Shepherds Bush Library",
         "adr":
            {"postal-code":"W12 8LJ",
             "country-name":"United Kingdom"},
         "geo":
            {"latitude":"51.505105",
             "longitude":"-0.225494"}}},
    {"id":"156",
     "title":"Barons Court Library",
     "url":"/v1/libraries/156.json",
     "supported":"yes",
     "distance":
        {"miles":0.85,
         "kilometres":1.37},
     "url_templates":
        {"check_availability":"/v1/availability/156/by-isbn/{isbn}.json"},
     "vcard":
        {"fn":"Barons Court Library",
         "org":"Barons Court Library",
         "adr":
            {"postal-code":"W14 8TG",
             "country-name":"United Kingdom"},
         "geo":
            {"latitude":"51.492533",
             "longitude":"-0.207111"}}},
    {"id":"155",
     "title":"Askew Road Library",
     "url":"/v1/libraries/155.json",
     "supported":"yes",
     "distance":
        {"miles":0.99,
         "kilometres":1.59},
     "url_templates":
        {"check_availability":"/v1/availability/155/by-isbn/{isbn}.json"},
     "vcard":
        {"fn":"Askew Road Library",
         "org":"Askew Road Library",
         "adr":
            {"postal-code":"W12 9AS",
             "country-name":"United Kingdom"},
         "geo":
            {"latitude":"51.50313",
             "longitude":"-0.243006"}}}]}

Checking book availability

Availability requests are not very reliable. This service acts as a proxy by checking external library OPACs. As a result, the response times will be much slower than any of the other types of requests described. In addition, very few of these OPACs offer public web APIs for accessing availability information, so in many cases web scraping is used to extract information.

Another limitation is the fact that an ISBN refers to one particular edition of a book. Checking a library for an ISBN does not provide availability information about other editions of the book. To see if there are other editions of a book, you can use the xISBN web service.

Request

To check if a book is available, you will need to supply an ISBN and specify one or more libraries to check. The path segment used above to find libraries is also used in availability requests to identify the libraries that need to be checked for book availability.

However, due to the slow response times of availability checks, a maximum of 5 libraries will be checked for each request. The more libraries checked, the longer you will have to wait for a response. If the response is not ready within 1 minute, you will receive a 504 error message indicating timeout. In such cases, you can retry your request by querying the libraries individually.

Template	http://librarylookup.org.uk/v1/availability/{id(s)/name/location}/by-isbn/{ISBN}
Example 1	http://librarylookup.org.uk/v1/availability/158/by-isbn/0745324827
Example 2	http://librarylookup.org.uk/v1/availability/158;211;233/by-isbn/0745324827
Example 3	http://librarylookup.org.uk/v1/availability/near=N7+0SF/by-isbn/0745324827
Example 4	http://librarylookup.org.uk/v1/availability/near=N7+0SF/by-isbn/0745324827?count=1

The examples above all check for the availability of a book identified by ISBN 0745324827. Example 1 checks a specific library identified by its ID (158). Example 2 checks 3 libraries identified by their IDs (158, 211 and 233). Example 3 checks 5 libraries near the given postcode (N7 0SF). Example 4 checks the nearest library to the given postcode (N7 0SF).

To get results in a different format, see representation formats above.

For a list of arguments you can pass, see arguments above.

Response

Availability response details are very similar to those desribed above for lists of libraries. This section will list the differences.

HTTP status codes

In addition to the HTTP status codes listed above, availability requests may return:

504	Timeout: could not check all libraries within 60 seconds

Body

Differences between the key-value pairs listed above:

type

'availability'

isbn

the ISBN passed in the request

results

list of libraries, each with this additional key

availability

'available' - book is available at the library
'on loan' - book is currently on loan
'no record' - library has no copies of the book
'unknown' - availability could not be checked

Example JSON output

{"status":"ok",
 "type":"availability",
 "url_templates":
    {"check_availability_near_postcode":"/v1/availability/near={postcode}/by-isbn/{isbn}.json"},
 "near":
    {"postal-code":"N7 0SF"},
 "isbn":"0745324827",
 "results":[
    {"availability":"no record",
     "id":"222",
     "title":"John Barnes Library",
     "url":"/v1/libraries/222.json",
     "supported":"yes",
     "distance":
        {"miles":0.26,
         "kilometres":0.42},
     "url_templates":
        {"check_availability":"/v1/availability/222/by-isbn/{isbn}.json"},
     "vcard":
        {"fn":"John Barnes Library",
         "org":"John Barnes Library",
         "adr":
            {"postal-code":"N7 0JN",
             "country-name":"United Kingdom"},
         "geo":
            {"latitude":"51.552203",
             "longitude":"-0.125675"}}},
    {"availability":"no record",
     "id":"226",
     "title":"Islington North Library",
     "url":"/v1/libraries/226.json",
     "supported":"yes",
     "distance":
        {"miles":0.35,
         "kilometres":0.57},
     "url_templates":
        {"check_availability":"/v1/availability/226/by-isbn/{isbn}.json"},
     "vcard":
        {"fn":"Islington North Library",
         "org":"Islington North Library",
         "adr":
            {"postal-code":"N7 6JX",
             "country-name":"United Kingdom"},
         "geo":
            {"latitude":"51.56029",
             "longitude":"-0.121938"}}},
    {"availability":"no record",
     "id":"220",
     "title":"Islington Central Library",
     "url":"/v1/libraries/220.json",
     "supported":"yes",
     "distance":
        {"miles":0.76,
         "kilometres":1.23},
     "url_templates":
        {"check_availability":"/v1/availability/220/by-isbn/{isbn}.json"},
     "vcard":
        {"fn":"Islington Central Library",
         "org":"Islington Central Library",
         "adr":
            {"postal-code":"N5 1PF",
             "country-name":"United Kingdom"},
         "geo":
            {"latitude":"51.549054",
             "longitude":"-0.107083"}}},
    {"availability":"available",
     "id":"76",
     "title":"Kentish Town Library",
     "url":"/v1/libraries/76.json",
     "supported":"yes",
     "distance":
        {"miles":0.88,
         "kilometres":1.41},
     "url_templates":
        {"check_availability":"/v1/availability/76/by-isbn/{isbn}.json"},
     "vcard":
        {"fn":"Kentish Town Library",
         "org":"Kentish Town Library",
         "adr":
            {"postal-code":"NW5 2AA",
             "country-name":"United Kingdom"},
         "geo":
            {"latitude":"51.549956",
             "longitude":"-0.140451"}}},
    {"availability":"no record",
     "id":"219",
     "title":"Archway Library",
     "url":"/v1/libraries/219.json",
     "supported":"yes",
     "distance":
        {"miles":0.94,
         "kilometres":1.51},
     "url_templates":
        {"check_availability":"/v1/availability/219/by-isbn/{isbn}.json"},
     "vcard":
        {"fn":"Archway Library",
         "org":"Archway Library",
         "adr":
            {"postal-code":"N19 5PH",
             "country-name":"United Kingdom"},
         "geo":
            {"latitude":"51.565706",
             "longitude":"-0.13561"}}}]}

Library Lookup

API Overview

Background

Retrieving a list of libraries

Request

By location

By name

By ID

Representation formats

Arguments

Response

HTTP status codes

HTTP content type

Body

Example JSON output

Checking book availability

Request

Response

HTTP status codes

Body

Example JSON output