Goodreads API
The Goodreads API returns book metadata, ratings and reviews as clean JSON.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
The primary book_detail endpoint returns a book's title, authors, average rating, ratings and reviews counts, the full rating distribution, genres, series and ISBN/ISBN13/ASIN plus publication data — the catalog data you would otherwise scrape from a Goodreads page. You can also search books, pull an author and their author_books, read reviews, and expand a series or a curated list. It is built for reading apps, book-discovery tools and literary research that need structured Goodreads data without a login or a fragile scraper. One ReefAPI key, one shared credit pool, the standard envelope.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/goodreads/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"query": "hunger games"
}
}{
"ok": true,
"meta": {
"api": "goodreads",
"endpoint": "search",
"mode": "live",
"latency_ms": 832.7,
"record_count": 5,
"bytes": 0,
"cache_hit": false,
"completeness_pct": 100,
"completeness_basis": {
"items": 5,
"checks": [
"book_id",
"title",
"author"
]
}
},
"data": {
"items": [
{
"book_id": "2767052",
"work_id": "2792775",
"title": "The Hunger Games",
"title_display": "The Hunger Games (The Hunger Games, #1)",
"author": "Suzanne Collins",
"author_id": "153394",
"avg_rating": 4.35,
"ratings_count": 10187171,
"num_pages": 374,
"url": "https://www.goodreads.com/book/show/2767052-the-hunger-games",
"image_url": "https://i.gr-assets.com/images/S/compressed.photo.goodreads.com/books/[redacted-phone]i/2767052._SX50_.jpg",
"description": "Winning means fame and fortune. Losing means certain death. The Hunger Games have begun. . . .\n\nIn the ruins of a place once known as North America lies the nation of Panem, a s…",
"rank": 1
},
{
"book_id": "6148028",
"work_id": "6171458",
"title": "Catching Fire",
"title_display": "Catching Fire (The Hunger Games, #2)",
"author": "Suzanne Collins",
"author_id": "153394",
"avg_rating": 4.36,
"ratings_count": 4289426,
"num_pages": 391,
"url": "https://www.goodreads.com/book/show/6148028-catching-fire",
"image_url": "https://i.gr-assets.com/images/S/compressed.photo.goodreads.com/books/[redacted-phone]i/6148028._SY75_.jpg",
"description": "Sparks are igniting.\nFlames are spreading.\nAnd the Capitol wants revenge.\n \nAgainst all odds, Katniss Everdeen has won the Hunger Games. She and fellow District 12 tribute Peeta M…",
"rank": 2
},
{
"book_id": "7260188",
"work_id": "8812783",
"title": "Mockingjay",
"title_display": "Mockingjay (The Hunger Games, #3)",
"author": "Suzanne Collins",
"author_id": "153394",
"avg_rating": 4.13,
"ratings_count": 3836432,
"num_pages": 390,
"url": "https://www.goodreads.com/book/show/7260188-mockingjay",
"image_url": "https://i.gr-assets.com/images/S/compressed.photo.goodreads.com/books/[redacted-phone]i/7260188._SY75_.jpg",
"description": "My name is Katniss Everdeen.\nWhy am I not dead?\nI should be dead.\n\nKatniss Everdeen, girl on fire, has survived, even though her home has been destroyed. Gale has escaped. Katniss…",
"rank": 3
}
],
"count": 5,
"query": "hunger games",
"source_layer": "auto_complete",
"result_cap": 8,
"result_cap_note": "Goodreads typeahead returns the top ~5-8 matches. Full SERP depth/sort/filter needs the AWS-WAF-walled /search (Phase-2 browser-mint) — see notes/anti-bot.md."
}
}What the Goodreads API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| book_detail | Full book record from Goodreads by book ID or URL: title, author(s), average rating, total ratings & text-reviews counts, 1-5 star distribution, genres, series, ISBN/ISBN-13/ASIN, publisher, publication year, page count, edition count, featured characters & settings, literary awards, retailer buy links, and up to 30 embedded reader reviews. | Content platforms call book_detail to get full book record from Goodreads by book ID or URL. | id, url, reviews_limit, include_pii |
| search | Search for books or authors on Goodreads by title, author name, or keyword → returns matching results with title, author, ISBN, book ID, average rating, and cover URL. | Research tools call search to search for books or authors on Goodreads by title, author name, or keyword →. | query |
| author | Author profile from Goodreads by author ID or URL: name, average rating, total ratings, birth/death date & place, genres, biography, and a sample of their books. | Community analysts call author to get author profile from Goodreads by author ID or URL. | id, url |
| author_books | An author's complete bibliography on Goodreads (paginated) by author ID or URL → every book with its title, book ID, average rating, ratings count, cover, and publication year. | Media monitors call author_books to get an author's complete bibliography on Goodreads (paginated) by author ID or URL → every book w…. | id, url, page |
| reviews | Fetch reader reviews for a book on Goodreads (by ID or URL) → each review includes the user, star rating, full review text, date, likes count, and spoiler flag. Returns up to 30 reviews per request. | Content platforms call reviews to fetch reader reviews for a book on Goodreads (by ID or URL) → each review includes the user,…. | id, url, book_id, include_pii |
| series | A Goodreads book series by series ID or URL → the ordered list of books in the series (title, book ID, URL) plus the primary/total work counts. | Research tools call series to get a Goodreads book series by series ID or URL → the ordered list of books in the series (title,…. | id, url |
| list | A Goodreads Listopia list by list ID or URL (paginated) → its ranked books with the community score, vote count, and rating for each, plus the list title and total voters. | Community analysts call list to get a Goodreads Listopia list by list ID or URL (paginated) → its ranked books with the community…. | id, url, page |
| lists_by_tag | Discover the most popular Goodreads Listopia lists for a topic tag (e.g. fantasy, romance, classics) — returns matching curated lists you can then pull with `list`. | Media monitors call lists_by_tag to discover the most popular Goodreads Listopia lists for a topic tag (e.g. | tag, page |
| genre | The most-read books in a Goodreads genre / shelf this week (e.g. fantasy, mystery, romance, science-fiction, young-adult) → trending books with cover and link. | Content platforms call genre to get the most-read books in a Goodreads genre / shelf this week (e.g. | genre |
| quotes | Quotes from Goodreads — either every quote BY an author (author_id) or every quote FROM a book (work_id, found in book_detail.book.work_id). Paginated; each quote has its text, source title, like count, and topic tags. | Research tools call quotes to get quotes from Goodreads. | author_id, work_id, book_id, id, url, ... |
Call search from your stack
curl -X POST https://api.reefapi.com/goodreads/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"hunger games"}'import requests
r = requests.post(
"https://api.reefapi.com/goodreads/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"query": "hunger games"
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/goodreads/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"query": "hunger games"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.goodreads.search with {"query":"hunger games"}.Who uses this API and why
- Reading and book-tracking apps call book_detail to enrich a title with cover, rating distribution and genres from an ISBN.
- Recommendation engines use author_books and series to build 'more like this' shelves.
- Literary researchers pull reviews to analyze sentiment and themes across a book's reader base.
Questions developers ask before integrating
What is the Goodreads API?
Goodreads API is a ReefAPI endpoint group for books, ratings, reviews and author profiles. It returns live JSON through POST requests under /goodreads/v1.
Is the Goodreads API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. Goodreads calls use the same shared credit balance as every other ReefAPI engine.
Do I need a Goodreads login or account?
No login to Goodreads is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the Goodreads data?
The page example is captured from a live book_detail call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the Goodreads API use?
Goodreads actions currently cost 1 credit per successful call. Failed or blocked calls are free, and all APIs draw from one credit pool.
Can I call Goodreads from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call goodreads actions with the same key, credit pool and JSON envelope used by normal REST requests.
Is the Goodreads API a Goodreads scraper?
It is the managed alternative to a DIY Goodreads scraper. Instead of building and maintaining your own scraper — proxies, headless browsers, captcha and constant breakage — you call one ReefAPI endpoint and get the same books, ratings, reviews and author profiles back as clean JSON.
Why does my Goodreads scraper keep getting blocked?
Most Goodreads scrapers break on anti-bot defenses, rate limits and IP bans that need rotating residential proxies and browser fingerprinting to clear. ReefAPI handles all of that for you — no proxies, no captchas, no maintenance — and returns live JSON. Blocked or failed calls are free.