Goodreads API & Scraper
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.
Goodreads book id, work id, ISBN, ISBN13 and ASIN: which key opens which door
Goodreads uses at least six identifiers and they are not interchangeable, which is why a lookup that works for book_detail fails for quotes. The rule is that a book id points at one edition and a work id points at the title across every edition. Measured on 2026-08-27 with The Hunger Games and Sunrise on the Reaping.
| Identifier | Where it comes from | What it resolves | Measured |
|---|---|---|---|
| book id | the digits in /book/show/<id>-slug | one edition, through book_detail and reviews | 2767052 returned the hardcover, 374 pages, ISBN 0439023483 |
| work id | book_detail.book.work_id | the title across all editions | 2792775; /work/quotes/2792775 returned 30 quotes with has_more true |
| isbn | book_detail output only | the print edition | 0439023483 |
| isbn13 | book_detail output only | the same print edition | 9780439023481 |
| asin | book_detail output only | equal to isbn on both print books measured, so not a Kindle ASIN | 0439023483 and 1546171460 |
| author id | the digits in /author/show/<id> | author, author_books and author-scope quotes | 153394 returned Suzanne Collins, avg_rating 4.3, books_count 10 |
| series id | the digits in /series/<id>-slug | the books in a series | 73758 returned 5 books, primary_works_count 3, total_works_count 5 |
| list id | the digits in /list/show/<id> | a Listopia list | 1 is the Best Books Ever list |
There is no ISBN or ASIN lookup. book_detail accepts id or url and nothing else, and isbn/isbn13/asin are outputs you receive after you already have the book id. In the measured search response for "hunger games", items carried book_id, work_id and author_id but no isbn at all, so resolving an ISBN takes a search followed by a book_detail call.
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 difference between a Goodreads book id and a work id?
A book id identifies one edition; a work id identifies the title behind every edition of it. For The Hunger Games, book id 2767052 resolves to the 374-page Scholastic hardcover with ISBN 0439023483, while work id 2792775 is the novel itself. The distinction matters because two surfaces need the work id and will not take the book id: quotes resolves /work/quotes/2792775, and book_detail.book.editions.url points at /work/editions/2792775. book_detail returns both ids in the same payload, so fetch the book once and keep the pair.
Can I look up a book by ISBN or ASIN?
No. book_detail takes id or url and that is the whole vocabulary. isbn, isbn13 and asin are fields you get back, not keys you can send. One measured surprise: asin came back identical to isbn on both books tested, 0439023483 for The Hunger Games and 1546171460 for Sunrise on the Reaping, so it is the print ASIN Amazon derives from the ISBN-10 rather than a Kindle ASIN. If you start from an ISBN, run search with the ISBN as the query text and then call book_detail on the book_id you get back.
How do I read the ratings_dist array?
It is five integers ordered from 1 star to 5 stars. The Hunger Games measured on 2026-08-27 returned [134272, 242952, 1118477, 3108989, 5646008], which sums to exactly 10,250,698, the same value as ratings_count. That is the check worth running: if your sum does not match ratings_count, you have parsed the array in the wrong order or dropped a bucket. reviews_count (275,980) is a different metric entirely, counting written reviews, so it is always far smaller than ratings_count.
Why does the series action return books out of order?
Because books[] in a series response carries only book_id, title and url with no position field, and the source order is not reading order. Series 73758 returned The Ballad of Songbirds and Snakes, Sunrise on the Reaping, The Hunger Games, Catching Fire and Mockingjay in that sequence. The position lives elsewhere: book_detail.book.series[].placement, which is a string and can be fractional. The Hunger Games returned placement "1" and Sunrise on the Reaping returned "0.5", the usual Goodreads convention for a prequel. That is also why primary_works_count was 3 while total_works_count was 5.
Which Goodreads fields come back null, and why?
Three worth planning for, all measured on 2026-08-27. editions.count was null on both books tested even though editions.url was present and valid. author.followers was null on the author action, while the same author's follower count came back as 130,280 inside book_detail.book.authors[], so take follower counts from book_detail rather than author. death_date is null for a living author, which makes null meaningful there rather than missing. On the author record, avg_rating 4.3 and ratings_count 21,705,682 are lifetime totals across all their books, not one title.
How do reviews and book_detail differ if both return reviews?
book_detail embeds a sample under reviews_sample with reviews_sample_count. The reviews action returns the same material as a first-class list with more structure per review: id, rating, text, date, created_at_ms, likes, comments, spoiler, user and user_url. Review ids are Amazon-style URIs rather than numbers, for example kca://review:goodreads/amzn1.gr.review:goodreads.v1.EfRoRFXMVpqXJ6Prmskyww, so store them as strings. Both surfaces top out around 30 reviews per book because that is what the Goodreads page itself embeds; reviews_limit will not raise that ceiling and there is no deep review pagination.
Does the quotes action need an author id or a book id?
Either an author_id or a work_id, and the work id is the one people get wrong. Passing the book id 2767052 will not resolve a book's quotes; the work id 2792775 will, and it comes from book_detail.book.work_id. The measured call returned 30 quotes with count 30, scope "work", page 1 and has_more true, each carrying text, author, title, likes (19,131 on the top one) and tags. Pass author_id instead and scope switches to that author's whole quote collection.
Do I need the slug part of a Goodreads URL?
No, only the leading digits matter. /book/show/2767052-the-hunger-games resolves from 2767052 alone, and the same holds for /author/show/153394, /series/73758-the-hunger-games and /list/show/1. Every action also accepts the full url as an alternative to id, which is convenient if you are ingesting links rather than ids. All of these ids come back as JSON strings rather than numbers, so keep them as strings end to end.
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.