| 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. |
| 59 |
</tr> |
59 |
</tr> |
| ... |
|
... |
|
| 69 |
<th><code>page</code> / <code>limit<code></th> |
69 |
<th><code>page</code> / <code>limit<code></th> |
| 70 |
<td>Use for pagination, with <code>limit</code> corresponding to the page size. Note <code>page</page> starts at 1.</td> |
40 |
<td>Use for pagination, with <code>limit</code> corresponding to the page size. Note <code>page</code> starts at 1.</td> |
| 71 |
</tr> |
41 |
</tr> |
| 72 |
</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 |
|
| 73 |
|
73 |
|
| ... |
|
... |
|
| 111 |
The fields in the doc are described by Solr schema which can be found here: |
111 |
The fields in the doc are described by Solr schema which can be found here: |
| 112 |
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 |
| 113 |
|
113 |
|
| ... |
|
... |
|
| 192 |
- 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 |
192 |
- 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 |
|
