Open Library RESTful API

Open Library provides a RESTful API for accessing resources in multiple formats.

• Content
  
• Query
  
• History
  
• Save
  
• Status Codes

 

Content

To request any content, the requested format can be specified using Accept: header or as part of the URL.
The currently available formats are JSON and RDF.

$ curl http://openlibrary.org/authors/OL1A.json
{
    "name": "Sachi Rautroy",
    ...
}
$ curl -s -H 'Accept: application/json' https://openlibrary.org/books/OL1M
{
    "name": "Sachi Rautroy",
    ...
}

Optional callback parameter can be specified when the requested format is JSON.

$ curl http://openlibrary.org/authors/OL1A.json?callback=process
process({
    "name": "Sachi Rautroy",
    ...
});

The RDF format is available for books and for authors.

$ curl https://openlibrary.org/books/OL6807502M.rdf
<rdf:Description rdf:about="http://openlibrary.org/books/OL6807502M">
<!-- authors -->
<bibo:authorList rdf:parseType="Collection">
  <rdf:Description rdf:about="http://openlibrary.org/authors/OL1518080A">
     <rdf:value>Lawrence Lessig</rdf:value>
  </rdf:Description>
</bibo:authorList>
    <!-- bibliographic description -->
    <dcterms:title>Code and other laws of cyberspace</dcterms:title>
    <dcterms:publisher>Basic Books</dcterms:publisher>
    <rdvocab:placeOfPublication>New York</rdvocab:placeOfPublication>
    <dcterms:issued>1999</dcterms:issued>
    <dcterms:extent>xii, 297 p. :</dcterms:extent>
   ....
</rdf:RDF>
$ curl -H 'Accept: application/rdf+xml' https://openlibrary.org/books/OL6807502M.rdf
<rdf:Description rdf:about="http://openlibrary.org/books/OL6807502M">
<!-- authors -->
<bibo:authorList rdf:parseType="Collection">
  <rdf:Description rdf:about="http://openlibrary.org/authors/OL1518080A">
     <rdf:value>Lawrence Lessig</rdf:value>
  </rdf:Description>
</bibo:authorList>
   <!-- bibliographic description -->
    <dcterms:title>Code and other laws of cyberspace</dcterms:title>
</rdf:RDF>

Open Library also allows accessing editions of a work and works of an author using a simple URL format.

$ curl 'http://openlibrary.org/works/OL27258W/editions.json?limit=5'
{
    "size": 19,
    "links": {
        "self": "/works/OL27258W/editions.json?limit=5",
        "work": "/works/OL27258W",
        "next": "/works/OL27258W/editions.json?limit=5&offset=5"
    },
    "entries": [{
        "key": "/books/OL17987798M",
        "title": "Neuromantiker",
        ...
    }, ...]
}
$ curl http://openlibrary.org/authors/OL1A/works.json
{
    "size": 16,
    "links": {
        "self": "/authors/OL1A/works.json",
        "author": "/authors/OL1A"}
    },
    "entries": [{
        "key": "/works/OL14930760W",
        "title": "Satchidananda Raut Roy",
        ...
    }, ...]
}

 

Query

The Query API allows querying the Open Library system for matching objects.

$ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/authors/OL1A'
[
    {
        "key": "/books/OL1M"
    },
    {
        "key": "/books/OL4731M"
    },
    ...
]
$ curl -H 'Accept: application/json' 'https://openlibrary.org/query?type=/type/edition&authors=/authors/OL1A'
[
    {
        "key": "/books/OL1M"
    },
    {
        "key": "/books/OL4731M"
    },
    ...
]
$ curl 'http://openlibrary.org/query.json?type=/type/edition&works=/works/OL2040129W'
[
    {
        "key": "/books/OL9770407M"
    },
    {
        "key": "/books/OL21857767M"
    },
    ...
]

Additional properties of each object can be requested by passing a query parameter with empty value.

$ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/authors/OL1A&title='
[
    {
        "key": "/books/OL1M",
        "title": "Kabit\u0101."
    },
    {
        "key": "/books/OL4731M",
        "title": "Sacci Ra\u0304utara\u0304y\u0307a grantha\u0304bal\u0323i\u0304."
    },
    ...
]

All properties can be requested using a special query parameter *.

$ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/authors/OL1A&*='
[
    {
        "pagination": "8, 304 p.",
        ...
        "title": "Kabit\u0101.",
        ...
        "key": "/books/OL1M",
        ...
    },
    ...
]

Optional limit and offset parameters can be passed to limit the number of requests and offset in the results respectively. Unless any limit is specified, the responses is limited to 20 entries. Maximum allowed value of limit is 1000 due to performance reasons.

$ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/authors/OL1A&limit=2'
[
    {
        "key": "/books/OL1M"
    },
    {
        "key": "/books/OL4731M"
    }
]

Queries can also be specified by passing the query as JSON dictionary. The above mentioned approach is just a syntactic-sugar for this.

# curl fails because it doesn't escape query parameter
$ wget -q -O - 'http://openlibrary.org/query.json?query={"type": "/type/edition", "authors": "/authors/OL1A", "title": null, "limit": 2}'
[
    {
        "key": "/books/OL1M",
        "title": "Kabit\u0101."
    },
    {
        "key": "/books/OL4731M",
        "title": "Sacci Ra\u0304utara\u0304y\u0307a grantha\u0304bal\u0323i\u0304."
    }
]

Please note that this API should not be used for bulk downloads. Dumps of all data are provided at regular intervals and they should be used for bulk access.

 

History

Change history of any object can be accessed by passing ?m=history query parameter to the resource url.

$ curl http://openlibrary.org/books/OL1M.json?m=history
[
    {
        "comment": "test",
        "created": "2008-10-14T08:58:48.091739",
        ...
    },
    ...
]
$ curl -H 'Accept: application/json' https://openlibrary.org/books/OL1M?m=history
[
    {
        "comment": "test",
        "created": "2008-10-14T08:58:48.091739",
        ...
    },
    ...
]

The entries are sorted in the descending order of created time.
The number of entries are limited to 20 by default and a different limit can be specified by passing limit parameters.
Optional offset parameter can also be specified to get results starting from an offset.
Maximum allowed value of limit is 1000 due to performance reasons.

$ curl http://openlibrary.org/books/OL1M.json?m=history&limit=2&offset=1
[
    {
        "comment": "test table of contents",
        "created": "2008-10-13T06:46:27.278809",
        ...
    },
    {
        "comment": "test",
        "created": "2008-09-12T14:37:30.974510",
        ...
    }
]

Support for RSS and Atom formats will be available soon.

Recent Changes

Recent changes is available in JSON, RSS and Atom formats.

$ curl http://openlibrary.org/recentchanges.json
[
    {
        "comment": "new author",
        ...
    },
    ...
]
$ curl -H 'Accept: application/json' https://openlibrary.org/recentchanges
[
    {
        "comment": "new author",
        ...
    },
    ...
]

Parameters, type, key and author can be specified to limit the results to modifications to objects of specified type, specified key and by an author respectively. Also limit and offset can be specified to limit number of results and offset.

$ curl http://openlibrary.org/recentchanges.json?type=/type/page
...
$ curl http://openlibrary.org/recentchanges.json?author=/people/anand&offset=20&limit=20

Support for RSS and Atom formats will be available soon.

 

Login

To login to Open Library programatically, a POST request must be send to /account/login with username and password must be passed as a JSON dictionary.

$ curl -i -H 'Content-Type: application/json' -d '{"username": "joe", "password": "secret"}' https://openlibrary.org/account/login
HTTP/1.1 200 OK
Set-Cookie: session="/user/joe%2C2009-02-19T07%3A52%3A13%2C74fc6%24811f4c2e5cf52ed0ef83b680ebed861f"; Path=/

Upon successful login, a set-cookie header is returned in the response.

 

Save

Modifying objects can be done by sending a PUT request to the resource url with appropriate Content-Type header. The currently supported format is only JSON.

TODO: show an example

Please note that right now this only an internal API and works only from the localhost.

 

Status codes

200 OK

Status code 200 OK is returned when the request is handled successfully.

400 Bad Request

Status code 400 Bad Request is returned when there is any error in the provided input data.
The error message is specified in the response body.

403 Forbidden

Status code 403 Forbidden is returned for PUT/POST requests when the requesting user does not have the required permissions to modify the resource.

The request can be repeated by providing the required credentials.

404 Not Found

Status code 404 Not Found is returned when the requested resource is not found.

500 Internal Server Error

Status code 500 Internal Server Error is returned if handling the request causes any internal errors.
Debug information about the error may be provided in the response to help trouble-shooting the issue.