| 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 |
|
101 |
|
| ... |
|
... |
|
| 141 |
- ["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. |
141 |
- ["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. |
| 142 |
- ["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 users language. |
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 |
|
| 143 |
|
143 |
|
| ... |
|
... |
|
| 173 |
... |
173 |
... |
|
|
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 |
|
