It looks like you're offline.
Donate
English
Open Library logo

Open Library Search API → Diff

Added
Modified
Removed
Not changed
Revision 25 by Mek November 27, 2023
Revision 43 by Mek May 7, 2025
body
0 Open Library provides an experimental API to search. 0 ## [Developer Center](https://openlibrary.org/developers) → [APIs](https://openlibrary.org/developers/api) → Search API
1 1
2 **WARNING: This API is under active development and may change in future.** 2 **URL:** https://openlibrary.org/search.json
3 3
4 # Overview & Features
5 4
6 The Open Library Search API is one of the most convenient and complete ways to retrieve book data on Open Library. The API:
7
8 1. Is able to return data for **multiple** books in a single request/response
9 2. Returns both Work level information about the book, as well as Edition level information (such as)
10 3. Author IDs are returned which you can use to fetch the author's image, if available
11 4. Options are available to return Book Availability along with the response.
12 5. Powerful sorting options are available, such as star ratings, publication date, and number of editions.
13
14 # Endpoint
15
16 The endpoint for this API is:
17 https://openlibrary.org/search.json
18
19 # Examples
20
21 The URL format for API is simple. Take the search URL and add `.json` to the end. Eg:
22
23 * https://openlibrary.org/search.json?q=the+lord+of+the+rings
24 * https://openlibrary.org/search.json?title=the+lord+of+the+rings
25 * https://openlibrary.org/search.json?author=tolkien&sort=new
26 * https://openlibrary.org/search.json?q=the+lord+of+the+rings&page=2
27 * https://openlibrary.org/search/authors.json?q=twain
28
29 ## Using Thing IDs to get Images
30
31 You can use the `olid` (Open Library ID) for authors and books to fetch covers by olid, e.g.:
32 https://covers.openlibrary.org/a/olid/OL23919A-M.jpg
33
34 ## URL Parameters
35 35
... ...
51 51
52            The fields to get back from solr. Use the special value <code>*</code> to get all fields (although be prepared for a very large response!). 22            The <a href="https://github.com/internetarchive/openlibrary/blob/b4afa14b0981ae1785c26c71908af99b879fa975/openlibrary/plugins/worksearch/schemes/works.py#L38-L91">fields</a> to get back from solr. The special value <code>*</code> may be provided to fetch all fields (however this will result in an expensive response, please use sparingly).
53             <br /> 23             <br />
54            To fetch availability data from archive.org, add the special value, <code>availability</code>. Example: <a href="/search.json?q=harry%20potter&fields=*,availability&limit=1">/search.json?q=harry%20potter&fields=*,availability&limit=1</a>. This will fetch the availability data of the first item in the `ia` field. 24            To fetch availability data from archive.org, add the special value, <code>availability</code>. Example: <a href="/search.json?q=harry%20potter&fields=*,availability&limit=1">/search.json?q=harry%20potter&fields=*,availability&limit=1</a>. This will fetch the availability data of the first item in the `ia` field.
55        </tr> 25        </tr>
56        <tr> 26        <tr>
57            <th><code>sort<code></th> 27            <th><code>sort<code></th>
58            <td>You can sort the results by various facets such as <code>new</code>, <code>old</code>, <code>random</code>, or <code>key</code> (which sorts as a string, not as the number stored in the string). For a complete list of sorts facets look <a href="https://github.com/internetarchive/openlibrary/blob/abd73aa37ea27b4e7d70f521bfd1e30b7dc1dc6e/openlibrary/plugins/worksearch/schemes/works.py#L113-L132">here</a> (this link goes to a specific commit, be sure to look at the latest one for changes). The default is to sort by relevance. 28            <td>You can sort the results by various facets such as <code>new</code>, <code>old</code>, <code>random</code>, or <code>key</code> (which sorts as a string, not as the number stored in the string). For a complete list of sorts facets look <a href="https://github.com/internetarchive/openlibrary/blob/b4afa14b0981ae1785c26c71908af99b879fa975/openlibrary/plugins/worksearch/schemes/works.py#L119-L153">here</a> (this link goes to a specific commit, be sure to look at the latest one for changes). The default is to sort by relevance.
29        </tr>
30        <tr>
31            <th><code>lang<code></th>
32            <td>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 <code>fr</code> will prefer/display the French edition of a given work, but will still match works that don't have French editions. Adding <code>language:fre</code> on the other hand to the search query <i>will</i> exclude results that don't have a French edition.
33        </tr>
34        <tr>
35            <th><code>offset</code> / <code>limit<code></th>
36            <td>Use for pagination.</td>
37        </tr>
38        <tr>
39            <th><code>page</code> / <code>limit<code></th>
40            <td>Use for pagination, with <code>limit</code> corresponding to the page size. Note <code>page</code> starts at 1.</td>
59        </tr> 41        </tr>
60 </table> 42 </table>
43
44
45 ## Overview
46
47 The Open Library Search API is one of the most convenient and complete ways to retrieve book data on Open Library. The API:
48
49 1. Is able to return data for **multiple** books in a single request/response
50 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)
51 3. Author IDs are returned which you can use to fetch the author's image, if available
52 4. Options are available to return Book Availability along with the response.
53 5. Powerful sorting options are available, such as star ratings, publication date, and number of editions.
54
55 ## Examples
56
57 The URL format for API is simple. Take the search URL and add `.json` to the end. Eg:
58
59 * https://openlibrary.org/search.json?q=the+lord+of+the+rings
60 * https://openlibrary.org/search.json?title=the+lord+of+the+rings
61 * https://openlibrary.org/search.json?author=tolkien&sort=new
62 * https://openlibrary.org/search.json?q=the+lord+of+the+rings&page=2
63 * https://openlibrary.org/search/authors.json?q=twain
64
65 ## Using Thing IDs to get Images
66
67 You can use the `olid` (Open Library ID) for authors and books to fetch covers by olid, e.g.:
68 https://covers.openlibrary.org/a/olid/OL23919A-M.jpg
69
70
61 61
... ...
99 The fields in the doc are described by Solr schema which can be found here: 99 The fields in the doc are described by Solr schema which can be found here:
100 https://github.com/internetarchive/openlibrary/blob/00a05558c6d8e7bb770f4f2684664ad048531dac/conf/solr/conf/managed-schema.xml#L131-L225 110 https://github.com/internetarchive/openlibrary/blob/b4afa14b0981ae1785c26c71908af99b879fa975/openlibrary/plugins/worksearch/schemes/works.py#L38-L91
101 111
102 The schema is not guaranteed to be stable, but most common fields (e.g. title, IA ids, etc) should be safe to depend on. 112 The schema is not guaranteed to be stable, but most common fields (e.g. title, IA ids, etc) should be safe to depend on.
113
114 ## Getting edition information
115
116 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)](https://openlibrary.org/books/OL7170815M/The_Wonderful_Wizard_of_Oz), 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:
117
118 https://openlibrary.org/search.json?q=crime+and+punishment&fields=key,title,author_name,editions
119
120
121    {
122        "numFound": 2421,
123        "start": 0,
124        "numFoundExact": true,
125        "docs": [
126            {
127                "key": "/works/OL166894W",
128                "title": "Преступление и наказание",
129                "author_name": ["Фёдор Михайлович Достоевский"],
130                "editions": {
131                    "numFound": 290,
132                    "start": 0,
133                    "numFoundExact": true,
134                    "docs": [
135                        {
136                            "key": "/books/OL37239326M",
137                            "title": "Crime and Punishment"
138                        }
139                    ]
140                }
141            },
142        ...
143
144 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.
145
146 From these, relevance is further determined by boosting books that (1) match the user's language, (2) are readable, (3) have a cover.
147
148 You can see this in action in the search UI as well. Consider the following searches:
149
150 - ["sherlock holmes"](https://openlibrary.org/search?q=sherlock+holmes&mode=everything) - The first work is OL262463W, with the edition displayed [_Memoirs of Sherlock Holmes_ (OL7058607M)](/books/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.
151 - ["sherlock holmes language:fre"](https://openlibrary.org/search?q=sherlock+holmes+language%3Afre&mode=everything) - The same work is displayed as above, but now the displayed edition is [_Souvenirs sur Sherlock Holmes_ (OL8887270M)](/books/OL8887270M), selected because the user's query requires a book in French.
152 - ["sherlock holmes" for a French user](https://openlibrary.org/search?q=sherlock+holmes&mode=everything&lang=fr) - By setting `lang=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 is [_Souvenirs sur Sherlock Holmes_ (OL8887270M)](/books/OL8887270M) since this matches the user's language.
153 - ["souvenirs sur sherlock holmes"](https://openlibrary.org/search?q=souvenirs+sur+sherlock+holmes&mode=everything) - 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 be  [_Souvenirs sur Sherlock Holmes_ (OL8887270M)](/books/OL8887270M) since this best matches the user's query.
154
155
156 In the API, you can also fetch fields from editions separately from those on the work, like so:
157
158 https://openlibrary.org/search.json?q=crime+and+punishment&fields=key,title,author_name,editions,editions.key,editions.title,editions.ebook_access,editions.language
159
160    {
161        "numFound": 2421,
162        "start": 0,
163        "numFoundExact": true,
164        "docs": [
165            {
166                "key": "/works/OL166894W",
167                "title": "Преступление и наказание",
168                "author_name": ["Фёдор Михайлович Достоевский"],
169                "editions": {
170                    "numFound": 290,
171                    "start": 0,
172                    "numFoundExact": true,
173                    "docs": [
174                        {
175                            "key": "/books/OL37239326M",
176                            "title": "Crime and Punishment",
177                            "language": [
178                                "eng"
179                            ],
180                            "ebook_access": "public"
181                        }
182                    ]
183                }
184            },
185        ...
186
187 Notes:
188 - Currently only one edition is displayed ; we are planning to add support for pagination so you can specify `editions.row` or `editions.start`.
189 - You can add `&editions.sort` to override the default relevance logic and instead sort by a specific field.
190 - 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
title Open Library Search API Search API