Quickstart
Find a book and get its details. This takes about 5 minutes.
You will:
- Search for a book.
- Get the full record for the book you found.
Before you start
- You need
curlor Python 3. The curl samples pipe intopython3 -m json.toolonly to pretty-print the output. You can drop the pipe. - You do not need an API key or an account.
- Send a
User-Agentheader that names your app. The samples useopenlibrary-unofficial-docs/0.1. Replace it with your own app name.
Rate limits
Open Library's usage guidelines allow 1 request per second without identification. If your app makes regular calls, add a contact email to your User-Agent, for example MyApp/1.0 (you@example.org). Identified requests get 3 requests per second.
Step 1: Search for a book
Call /search.json with your search text in q. Use fields to get only the fields you need, and limit to cap the number of results.
curl -s -A "openlibrary-unofficial-docs/0.1" \
"https://openlibrary.org/search.json?q=the+lord+of+the+rings&fields=key,title,author_name,first_publish_year&limit=2" \
| python3 -m json.tool
Output (trimmed):
{
"numFound": 1105,
"start": 0,
"numFoundExact": true,
"q": "the lord of the rings",
"docs": [
{
"author_name": ["J.R.R. Tolkien"],
"first_publish_year": 1954,
"key": "/works/OL27448W",
"title": "The Lord of the Rings"
},
{
"author_name": ["J.R.R. Tolkien"],
"first_publish_year": 1954,
"key": "/works/OL27513W",
"title": "The Fellowship of the Ring"
}
]
}
Install requests:
pip install requests
Save this as search_books.py:
import requests
HEADERS = {"User-Agent": "openlibrary-unofficial-docs/0.1"}
params = {
"q": "the lord of the rings",
"fields": "key,title,author_name,first_publish_year",
"limit": 3,
}
response = requests.get(
"https://openlibrary.org/search.json",
params=params,
headers=HEADERS,
timeout=10,
)
response.raise_for_status()
data = response.json()
print(f"Found {data['numFound']} matches")
for book in data["docs"]:
authors = ", ".join(book.get("author_name", ["unknown"]))
print(f"{book['title']} ({book.get('first_publish_year')}) by {authors} -> {book['key']}")
Run it:
python3 search_books.py
Output:
Found 1105 matches
The Lord of the Rings (1954) by J.R.R. Tolkien -> /works/OL27448W
The Fellowship of the Ring (1954) by J.R.R. Tolkien -> /works/OL27513W
The Two Towers (1954) by J.R.R. Tolkien -> /works/OL27479W
Each result has a key, such as /works/OL27448W. A work is one book across all its editions. Use the key in the next step.
Note
numFound and the order of results change as the catalog changes. Your numbers may differ.
Step 2: Get the work
Add .json to the work key and request it.
curl -s -A "openlibrary-unofficial-docs/0.1" \
"https://openlibrary.org/works/OL27448W.json"
Output (trimmed to a few fields):
{
"key": "/works/OL27448W",
"title": "The Lord of the Rings",
"authors": [
{
"author": {"key": "/authors/OL26320A"},
"type": {"key": "/type/author_role"}
}
],
"subjects": [
"The Lord of the Rings",
"Fiction",
"English Fantasy fiction",
"..."
]
}
The full response also has description, covers, first_publish_date, subject_places, and more.
The author is a key, not a name. To get the name, request /authors/OL26320A.json.
What you did
- Searched the catalog with
/search.json. - Got a full work record with
/works/{id}.json.