Search API

Developer Center →APIs → Search API

URL:https://openlibrary.org/search.json

Overview

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 formultiple books in a single request/response
   
2. Returns both Work level information about the book (like author info, first publish year, etc), as well as Edition level information (like title, identifiers, covers, etc)
   
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.

Examples

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

• https://openlibrary.org/search.json?q=the+lord+of+the+rings
  
• https://openlibrary.org/search.json?title=the+lord+of+the+rings
  
• https://openlibrary.org/search.json?author=tolkien&sort=new
  
• https://openlibrary.org/search.json?q=the+lord+of+the+rings&page=2
  
• https://openlibrary.org/search/authors.json?q=twain

Using Thing IDs to get Images

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

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 returnsworks instead ofeditions. Awork is a collection of editions; for example there is only one work forThe 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 theeditions 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"                    }                ]            }        },    ...

Theeditions 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:

• "sherlock holmes" - The first work is OL262463W, with the edition displayedMemoirs of Sherlock Holmes (OL7058607M). This edition was selected because it matched the user's query, and it matched the user's language (my language is English), and because it was readable.
  
• "sherlock holmes language:fre" - The same work is displayed as above, but now the displayed edition isSouvenirs sur Sherlock Holmes (OL8887270M), selected because the user's query requires a book in French.
  
• "sherlock holmes" for a French user - By settinglang=fr in the URL, we can simulate the website as it would appear for a French user. This information is used to influence the results again, and the displayed edition isSouvenirs sur Sherlock Holmes (OL8887270M) since this matches the user's language.
  
• "souvenirs sur sherlock holmes" - Here as an English user, I search by the French title. So again I will see the same work as always, but the displayed edition will now also beSouvenirs sur Sherlock Holmes (OL8887270M) since this best matches the user's query.

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 specifyeditions.row oreditions.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