What readers actually thought, distribution and all
The Goodreads API returns book metadata, ratings and reviews as clean JSON.
10 active endpoints. Every call is 1 credit.
- POST/goodreads/v1/book_detail
- POST/goodreads/v1/search
- POST/goodreads/v1/author
- POST/goodreads/v1/author_books
- POST/goodreads/v1/reviews
- POST/goodreads/v1/series
- POST/goodreads/v1/list
- +3 more
What Goodreads endpoints does ReefAPI ship?
10 live read endpoints. Read-only data API: no writes, no account actions, no dashboard access on the target site.
Goodreads API
3 of 10 endpoints, ready to run
The book with its average rating, total ratings, review count, the full star distribution, genres, page count, format and description.
{ "ok": true, "meta": { "api": "goodreads", "endpoint": "book_detail", "mode": "live", "latency_ms": 3990.3, "record_count": 1, "cache_hit": false, "completeness_pct": 100 }, "data": { "book": { "id": "2767052", "work_id": "2792775", "title": "The Hunger Games", "title_complete": "The Hunger Games (The Hunger Games, #1)", "authors": [ { "name": "Suzanne Collins", "url": "https://www.goodreads.com/author/show/153394.Suzanne_Collins", "id": "153394", "role": "Author", "followers": 130333 } ], "description": "Winning means fame and fortune. Losing means certain death. The Hunger Games have begun. . . .\r\n\r\nIn the ruins of a place once known as North America lies the nation of Panem, a shining Capitol surrounded by twelve outlying districts. The Capitol is harsh and cruel and keeps the districts in line by forcing them all to send one boy and one girl between the ages of twelve and eighteen to participate in the annual Hunger Games, a fight to the death on live TV.\r\n\r\nSixteen-year-old Katniss Everdeen regards it as a death sentence when she steps forward to take her sister's place in the Games. But Katniss has been close to dead before-and survival, for her, is second nature. Without really meaning to, she becomes a contender. But if she is to win, she will have to start making choices that weigh survival against humanity and life against love.", "avg_rating": 4.36, "ratings_count": 10254423, "reviews_count": 276147, "ratings_dist": [ 134312, 243001, 1118781 ], "genres": [ "Young Adult", "Dystopia", "Fiction" ], "num_pages": 374, "format": "Hardcover", "isbn": "0439023483", "isbn13": "9780439023481", "asin": "0439023483", "language": "English", "publisher": "Scholastic Press", "publish_year": 2008, "original_publish_year": 2008, "original_title": "The Hunger Games", "series": [ { "title": "The Hunger Games", "url": "https://www.goodreads.com/series/73758-the-hunger-games", "placement": "1" } ], "cover": "https://m.media-amazon.com/images/S/compressed.photo.goodreads.com/books/1586722975i/2767052.jpg", "url": "https://www.goodreads.com/book/show/2767052-the-hunger-games", "characters": [ "Katniss Everdeen", "Peeta Mellark", "Cato (Hunger Games)" ], "places": [ "District 12, Panem", "Capitol, Panem", "Panem" ], "awards": [ { "name": "Locus Award", "category": "Best Young Adult Book (2009) and for Illustrated and Art Book", "year": 2025, "designation": "NOMINEE", "url": "https://www.goodreads.com/award/show/46-locus-award" }, { "name": "Georgia Peach Book Award", "category": null, "year": 2009, "designation": "WINNER", "url": "https://www.goodreads.com/award/show/214-georgia-peach-book-award" }, { "name": "Buxtehuder Bulle", "category": null, "year": 2009, "designation": "WINNER", "url": "https://www.goodreads.com/award/show/295-buxtehuder-bulle" } ], "buy_links": [ { "name": "Amazon", "url": "https://www.amazon.com/gp/product/B002MQYOFW/ref=x_gr_bb_kindle?caller=Goodreads&tag=x_gr_bb_kindle-20" }, { "name": "Audible", "url": "https://www.amazon.com/s?k=The+Hunger+Games&i=audible&ref=x_gr_bb_audible&tag=x_gr_bb_audible-20" }, { "name": "Barnes & Noble", "url": "https://www.barnesandnoble.com/w/?ean=9780439023481" } ], "shelves_url": "https://www.goodreads.com/work/shelves/2792775-the-hunger-games", "editions": { "count": null, "url": "https://www.goodreads.com/work/editions/2792775" }, "reviews_sample": [ { "id": "kca://review:goodreads/amzn1.gr.review:goodreads.v1.EfRoRFXMVpqXJ6Prmskyww", "rating": 5, "text": "rereading this for the first time in 10 years and it feels more relevant than ever. truly a timeless classic.", "likes": 2041, "comments": 19, "date": "2014-12-23", "created_at_ms": 1419307926000, "spoiler": false }, { "id": "kca://review:goodreads/amzn1.gr.review:goodreads.v1.Hh6KGcTIX5DTlR2TKad7YQ", "rating": 5, "text": "My \"Epic Book Recipe\" Checklist for The Hunger Games: \n\n1. A sharp and intelligent heroine with just the right amount of emotion who gives in to absolutely nothing and no one? \n\n2. A sweet and sensitive hero who loves and supports the heroine unconditionally? \n\n3. An original setting with a unique and thrilling plot? \n\n4. A couple of earth-shattering shocks every now and then to keep the readers' mind reeling? \n\n5. Extraordinary side characters from interesting backgrounds who possess the much-needed Voice of Reason and/or Humor in every crisis? \n\n6. Desperate circumstances that force me to bite my nails in anxiety? \n\n7. An ending that provides the perfect premise for the sequel but also concludes the present book? \n\nLike I said, EPIC. \n\n\nFor more reviews, visit my blog.", "likes": 1538, "comments": 168, "date": "2009-10-20", "created_at_ms": 1256002821000, "spoiler": false }, { "id": "kca://review:goodreads/amzn1.gr.review:goodreads.v1.z_A1Ex53N4FbaAFWT0Tgfg", "rating": 4, "text": "Suzanne Collins has balls ovaries of steel to make us willingly cheer for a teenage girl to kill other children. In a YA book. \nTwo reasons why this book rocks: (a) It is not Twilight, and (b) I really hate reality shows. \n\n \n\n Seriously, how long would it take for reality shows to evolve from \"Survivor\" to \"Hunger Games\"? \n\n\nYes, this book is full of imperfections. It often requires a strenuous suspension of disbelief. It can cause a painful amount of eye-rolling and shaking fist at the book pages. Its style is choppy and the first-person present tense gets annoying. The story is simple, and the message is heavy-handed. But is does set a better example for young impressionable pre-teens than gushing stories about sparkly co-dependency. And here is an obligatory taken out of contest Twilight-bashing quote: \n “But just the fact that he was sparkling leads me to doubt everything that happened.” \n So why did I add it to my to-read list for my future (hypothetical) daughter? Because Katniss is cool and a badass. She is fierce, independent, resourceful, intelligent, and skilled. She is loyal to her friends and family. She is a survivor. She will never allow a guy to carry her around as though she is a delicate flower. She skewers that apple in the pig's mouth with an arrow in front of the Gamemakers in the most awesome way imaginable. For all that, I love this imperfect, surly, prickly, sullen and perpetually pissed-off, quick to jump to judgment, and sometimes clueless girl. \n\n \n\nAnd I love this book because - despite The Hunger Games being YA literature that seems to hinge on the romantic puppy love - the happiness of Katniss does not revolve solely around a cute male lead. Yes, there is a (hated) love triangle here *eyeroll* but there are other issues that occupy Katniss' mind - such as the survival of her friends, family, and herself rather than just pining over a cute boy. (*)\n * Unlike other so-called \"books\", where a boyfriend of a few months dumping you is a valid reason for catatonia and almost-suicide.(**)\n\n** And yet we still get readers who divide themselves into the incredibly annoying \"Team Peeta\" and \"Team Gale\". (***)\n\n*** Because clearly nothing else ever matters besides sappy love - in a book about children murdering each other. *eyeroll* \n \n\n \n\nNow, here is what bugged me about the romance that DID make it into the book. There is actually a LOST OPPORTUNITY here to have a YA book where people CAN be just friends, where devotion and loyalty stem from friendship and respect and not from attraction. \n\nKatniss and Peeta could have had plenty of other reasons to care for each other that don't include puppy love - they are from the same district, same school, he gave her that bread, she trades with his dad, etc. But alas, that did not happen. I understand that Collins had to cater to the way that YA publishers and Hollywood tend to view us, the female audience. At least Katniss escapes the perils of insta-love. But poor Peeta - all of his actions are colored by him being \"Lover Boy\", and I think it detracts from his personality and reduces him from a kind compassionate person to a fool in love who'd do anything for Katniss only because of his physical attraction to her. Yeah...\n\n...Rue...Oh, Rue... \n\nNow, back to the GOOD. Rue, my favorite character. Little, fragile, almost-too-perfect Rue who was clearly doomed from the start. Who despite her appearance was neither weak nor helpless. Whose death scene brought the human side to Katniss (who, until that point, was almost bordering on robotic). There was real grief and anger and sadness in that scene, and from that point on I began to care. \n\nSuzanne Collins strictly follows the \"show, don't tell\" rule. (Actually, she does it to such an extent that the book reads almost like a screenplay.) The plot moves along at a fast pace, only slowing down a bit in the drawn out Capitol makeover and cave makeout sessions. Collins does not shy away from gruesome scenes, making many parts of the book hit home.\n----------\nI enjoyed it despite the imperfections. Katniss easily beats the majority of the popular YA heroines. And because of all her coolness, this gets 3.75 stars. \n \"Exactly how am I supposed to work in a thank-you in there? Somehow it just won't seem sincere if I'm trying to slit his throat.\" \n-----------------------------------------\n\n EDITED TO ADD:\n \nSo I saw the movie today. All I have to say - Suzanne Collins may have given life to Katniss, but Jennifer Lawrence definitely gave her heart. Lawrence's Katniss has such emotional depth, and she brings such truthfulness to her character. Excellent adaptation with a great balance of tugging on the heartstrings and darkness.\n\n I CRIED TWICE (yes, apparently I am less of a cynic than I thought). \nFirst time - when Katniss volunteers for Prim and people salute her. I JUST CHOKED UP. It felt so real. I have a brother who is much younger than me, and all I could think at that moment was how I would do the exact same thing for him WITHOUT ANY HESITATION. It wouldn't even be a choice. Just like it wasn't for Katniss. *Sob* \nThe second time I teared up - Rue. Oh Rue... And the salute from District 11 - so powerful and so touching. I...I...I just can't... \n\nPLEASE EXCUSE ME WHILE I GO AND GRAB A BOX OF TISSUES. OR TWO. OR TEN. *SOB*", "likes": 1457, "comments": 167, "date": "2010-12-08", "created_at_ms": 1291766407000, "spoiler": false } ], "reviews_sample_count": 30 } } }
How the Goodreads API works
Goodreads is a normal ReefAPI surface — the same four rules that hold for every other engine on the key.
No OAuth app, no request signing, no per-site account. One key covers all 184 engines.
Every route is a POST with a JSON body. Parameters are validated against the published schema before anything is charged.
Credits, not seats. Failed and blocked calls are never charged, and cache hits cost nothing.
One envelope everywhere. meta carries latency_ms, record_count and the endpoint that answered.
Reading the shape of an opinion, not just its average
A 4.36 average can be a book everyone mildly likes or a book half the readers love and a quarter hate. The average cannot tell them apart; the distribution can.
{"query": "hunger games"}Returns the id along with the average and the ratings count, so a shortlist is one call.
{"id": "2767052"}Then the full record with the star distribution as an array — which is what separates a polarising book from a broadly liked one.
Ratings counts here run into the millions on major titles, so the distribution is statistically meaningful rather than a handful of opinions.
curl -X POST https://api.reefapi.com/goodreads/v1/book_detail \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"id":"2767052"}'{
"ok": true,
"data": { … },
"meta": {
"api": "goodreads",
"endpoint": "book_detail",
"mode": "live",
"latency_ms": …,
"record_count": …
},
"error": null
}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.
Whose opinion this is, and how the search behaves
Measured on a major title and on searches.
Ratings by star level come back as an array alongside the average and the total. Polarisation is invisible in a mean and obvious in a distribution, and for anything doing recommendation that difference is the signal.
The display title carries the series and the position within it, and there is a series endpoint for the full ordering. Reading order is the single most common question about a book that is not the first in its series.
The genres here come from what readers shelved a book as, not from a publisher's category. That is messier and considerably more useful for recommendation, because it reflects how the book is actually read.
The search layer is the site's own autocomplete and caps at a small number of the strongest matches — the response says so explicitly, with the cap and a note. It is built for resolving a title to an id, not for enumerating a catalogue.
Reviews are written by named members. Personal fields are excluded unless the call asks for them, because a review is public writing and a reviewer is still a person.
What people build with Goodreads
The jobs this data is most often used for.
endpoints
credit per call
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.
What Goodreads data costs
The cheapest call here is 1 credit, so $15/mo (Pro) buys 10,000 of them — $1.50 per 1,000 credits. Credits roll over and never expire, and failed or blocked calls are not charged.
Full pricing →- 1,000 free credits on signup, no card
- One key, all 184 APIs, one credit pool
- Failed and blocked calls are never charged
- Credits roll over and never expire
Call it in two lines
Sign up, get 1,000 credits and one key that works on every engine. Then this is the whole protocol.
curl -X POST https://api.reefapi.com/goodreads/v1/book_detail \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"id":"2767052"}'import requests
r = requests.post(
"https://api.reefapi.com/goodreads/v1/book_detail",
headers={"x-api-key": REEF_KEY},
json={
"id": "2767052"
},
)
print(r.json()["data"])Have a question? We got answers.
The questions people actually ask before wiring up Goodreads.
Get a free key →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.
25 Media, Film & Knowledge APIs on the same key
One key, one credit pool, one response envelope. If you are pulling Goodreads, you are one call away from the rest of the category — no second contract, no second integration.
Need something this API does not do?
Name the endpoint, the field, or a source we do not carry yet. We ship new APIs every week and you would be first to get the key. Real people read every message and reply the same day.
Try it on your own data before you pay anything
The call above is the real endpoint, not a recording. A free key gives you 1,000 credits, the other 183 APIs, and the same envelope everywhere.
Endpoints, parameters and credit costs on this page are read from the live catalog and cannot drift from what the API accepts. Field notes were captured on 2026-08-30.