It looks like you're offline.
Open Library logo
additional options menu
⚠ Urge publishers to restore access to 500,000 removed library books: Sign Letter - Learn More
Last edited by Drini
November 30, 2023 | History

Open Library Search API

Open Library provides an experimental API to search.

WARNING: This API is under active development and may change in future.

Overview & Features

The Open Library Search API is one of the most convenient and complete ways to retrieve book data on Open Library. The API:

  1. Is able to return data for multiple books in a single request/response
  2. Returns both Work level information about the book, as well as Edition level information (such as)
  3. Author IDs are returned which you can use to fetch the author's image, if available
  4. Options are available to return Book Availability along with the response.
  5. Powerful sorting options are available, such as star ratings, publication date, and number of editions.

Endpoint

The endpoint for this API is:
https://openlibrary.org/search.json

Examples

The URL format for API is simple. Take the search URL and add .json to the end. Eg:

Using Thing IDs to get Images

You can use the olid (Open Library ID) for authors and books to fetch covers by olid, e.g.:
https://covers.openlibrary.org/a/olid/OL23919A-M.jpg

URL Parameters

Parameter Description
q The solr query. See Search HowTo for sample queries
fields The fields to get back from solr. Use the special value * to get all fields (although be prepared for a very large response!).
To fetch availability data from archive.org, add the special value, availability. Example: /search.json?q=harry%20potter&fields=*,availability&limit=1. This will fetch the availability data of the first item in the `ia` field.
sort You can sort the results by various facets such as new, old, random, or key (which sorts as a string, not as the number stored in the string). For a complete list of sorts facets look here (this link goes to a specific commit, be sure to look at the latest one for changes). The default is to sort by relevance.
lang The users language as a two letter (ISO 639-1) language code. This influences but doesn't exclude search results. For example setting this to fr will prefer/display the French edition of a given work, but will still match works that don't have French editions. Adding language:fre on the other hand to the search query will exclude results that don't have a French edition.
offset / limit Use for pagination.
page / limit Use for pagination, with limit corresponding to the page size. Note page starts at 1.

Response Format

The response with be of the following format.

{
    "start": 0,
    "num_found": 629,
    "docs": [
        {...},
        {...},
        ...
        {...}]
}

Each document specified listed in "docs" will be of the following format:

{
    "cover_i": 258027,
    "has_fulltext": true,
    "edition_count": 120,
    "title": "The Lord of the Rings",
    "author_name": [
        "J. R. R. Tolkien"
    ],
    "first_publish_year": 1954,
    "key": "OL27448W",
    "ia": [
        "returnofking00tolk_1",
        "lordofrings00tolk_1",
        "lordofrings00tolk_0",
    ],
    "author_key": [
        "OL26320A"
    ],
    "public_scan_b": true
}

The fields in the doc are described by Solr schema which can be found here:
https://github.com/internetarchive/openlibrary/blob/b4afa14b0981ae1785c26c71908af99b879fa975/openlibrary/plugins/worksearch/schemes/works.py#L38-L91

The schema is not guaranteed to be stable, but most common fields (e.g. title, IA ids, etc) should be safe to depend on.

Getting edition information

By default, the search endpoint returns works instead of editions. A work is a collection of editions; for example there is only one work for The Wonderful Wizard of Oz (OL18417W), but there are 1029 editions, over many languages! Sometimes you might want to fetch data about editions as well as works. That is what the editions field is for:

https://openlibrary.org/search.json?q=crime+and+punishment&fields=key,title,author_name,editions

{
    "numFound": 2421,
    "start": 0,
    "numFoundExact": true,
    "docs": [
        {
            "key": "/works/OL166894W",
            "title": "Преступление и наказание",
            "author_name": ["Фёдор Михайлович Достоевский"],
            "editions": {
                "numFound": 290,
                "start": 0,
                "numFoundExact": true,
                "docs": [
                    {
                        "key": "/books/OL37239326M",
                        "title": "Crime and Punishment"
                    }
                ]
            }
        },
    ...

The editions sub-object contains the editions of this work that match the user's query (here, "crime and punishment"), sorted so the best (i.e. most relevant) is at the top. Matching editions are first selected by forwarding any search fields in the query that apply to editions (e.g. publisher, language, ebook_access, has_fulltext, etc). Any un-fielded search terms (e.g. "crime and punishment", above) are also applied, but are not require to all match.

From these, relevance is further determined by boosting books that (1) match the user's language, (2) are readable, (3) have a cover.

You can see this in action in the search UI as well. Consider the following searches:

In the API, you can also fetch fields from editions separately from those on the work, like so:

https://openlibrary.org/search.json?q=crime+and+punishment&fields=key,title,author_name,editions,editions.key,editions.title,editions.ebook_access,editions.language

{
    "numFound": 2421,
    "start": 0,
    "numFoundExact": true,
    "docs": [
        {
            "key": "/works/OL166894W",
            "title": "Преступление и наказание",
            "author_name": ["Фёдор Михайлович Достоевский"],
            "editions": {
                "numFound": 290,
                "start": 0,
                "numFoundExact": true,
                "docs": [
                    {
                        "key": "/books/OL37239326M",
                        "title": "Crime and Punishment",
                        "language": [
                            "eng"
                        ],
                        "ebook_access": "public"
                    }
                ]
            }
        },
    ...

Notes:
- Currently only one edition is displayed ; we are planning to add support for pagination so you can specify editions.row or editions.start.
- You can add &editions.sort to override the default relevance logic and instead sort by a specific field.
- You can see the exact boosting logic in the code here: https://github.com/internetarchive/openlibrary/blob/dc49fddb78a3cb25138922790ddd6a5dd2b5741c/openlibrary/plugins/worksearch/schemes/works.py#L439-L448

History

November 30, 2023 Edited by Drini Update code links
November 30, 2023 Edited by Drini Fix html
November 30, 2023 Edited by Drini Add more parameters to url params table
November 28, 2023 Edited by Drini Fix code link
February 27, 2013 Created by Anand Chitipothu documented search API.