# Goodreads API scraper — book details, ratings, reviews, author profiles & bibliographies, series, Listopia lists, genre charts, and quotes from goodreads.com (no account required)

> 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.
> ReefAPI engine `goodreads` · 10 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/goodreads/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /goodreads/v1/book_detail — 1 credit
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.

**Parameters:**
- `id` (string, optional) — Goodreads numeric book id (the digits in /book/show/<id>-slug). Supply `id` OR `url`.
- `url` (string, optional) — Full Goodreads book URL — an alternative to `id`.
- `reviews_limit` (integer, optional, default 30) — Maximum number of reviews to return per book (up to ~30 are embedded on the Goodreads book page; default 30).
- `include_pii` (boolean, optional, default false) — If true, do NOT redact reviewer display data (default redacts phone/email, keeps public name).

**Returns:** book{} — title, authors[], avg_rating, ratings_count, reviews_count, ratings_dist, genres, series, isbn/isbn13/asin, publisher, publish_year, num_pages, characters[], places[], awards[], buy_links[], editions, reviews_sample[]

**Example request body:**
```json
{
  "id": "2767052"
}
```

### POST /goodreads/v1/search — 1 credit
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.

**Parameters:**
- `query` (string, required) — Book/author search text (autocomplete typeahead → results[]).

**Returns:** items[] (title, author, author_id, isbn, book_id, avg_rating, url, image_url), count, query

**Example request body:**
```json
{
  "query": "hunger games"
}
```

### POST /goodreads/v1/author — 1 credit
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.

**Parameters:**
- `id` (string, optional) — Goodreads numeric author id (the digits in /author/show/<id>). Supply `id` OR `url`.
- `url` (string, optional) — Full Goodreads author URL — an alternative to `id`.

**Returns:** author{} — name, avg_rating, ratings_count, birth_date/place, genres, bio, books[]

**Example request body:**
```json
{
  "id": "153394"
}
```

### POST /goodreads/v1/author_books — 1 credit
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.

**Parameters:**
- `id` (string, optional) — Goodreads numeric author id (the digits in /author/show/<id>). Supply `id` OR `url`.
- `url` (string, optional) — Full Goodreads author URL — an alternative to `id`.
- `page` (integer, optional, default 1) — 1-based page number. Use meta.has_more / data.has_more to know when to stop; values < 1 clamp to 1.

**Returns:** books[] (book_id, title, url, avg_rating, ratings_count, cover, published_year), author_name, count, page, has_more

**Example request body:**
```json
{
  "id": "153394"
}
```

### POST /goodreads/v1/reviews — 1 credit
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.

**Parameters:**
- `id` (string, optional) — Goodreads numeric book id (the digits in /book/show/<id>-slug). Supply `id` OR `url`.
- `url` (string, optional) — Full Goodreads book URL — an alternative to `id`.
- `reviews_limit` (integer, optional, default 30) — Maximum number of reviews to return per book (up to ~30 are embedded on the Goodreads book page; default 30).
- `include_pii` (boolean, optional, default false) — If true, do NOT redact reviewer display data (default redacts phone/email, keeps public name).

**Returns:** reviews[] (user, rating, text, date, likes, spoiler), count, book_id

### POST /goodreads/v1/series — 1 credit
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.

**Parameters:**
- `id` (string, optional) — Goodreads numeric series id (the digits in /series/<id>-slug). Supply `id` OR `url`.
- `url` (string, optional) — Full Goodreads series URL — an alternative to `id`.

**Returns:** title, primary_works_count, total_works_count, books[] (book_id, title, url), count

**Example request body:**
```json
{
  "id": "73758"
}
```

### POST /goodreads/v1/list — 1 credit
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.

**Parameters:**
- `id` (string, optional) — Goodreads Listopia list id (the digits in /list/show/<id>). Supply `id` OR `url`.
- `url` (string, optional) — Full Goodreads list URL — an alternative to `id`.
- `page` (integer, optional, default 1) — 1-based page number. Use meta.has_more / data.has_more to know when to stop; values < 1 clamp to 1.

**Returns:** title, total_books, voters, description, books[] (rank, book_id, title, author, score, votes, avg_rating, ratings_count, url), count, page, has_more

**Example request body:**
```json
{
  "id": "1"
}
```

### POST /goodreads/v1/lists_by_tag — 1 credit
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`.

**Parameters:**
- `tag` (string, required) — A Listopia topic tag (e.g. fantasy, romance, classics, ya) → the most popular curated lists for that topic.
- `page` (integer, optional, default 1) — 1-based page number. Use meta.has_more / data.has_more to know when to stop; values < 1 clamp to 1.

**Returns:** lists[] (list_id, title, url), tag, count, page, has_more

**Example request body:**
```json
{
  "tag": "fantasy"
}
```

### POST /goodreads/v1/genre — 1 credit
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.

**Parameters:**
- `genre` (string, required) — A Goodreads genre / shelf slug (e.g. fantasy, fiction, mystery, romance, science-fiction, young-adult, non-fiction) → the most-read books for that genre.

**Returns:** books[] (book_id, title, url, cover), genre, related_genres[], count

**Example request body:**
```json
{
  "genre": "fantasy"
}
```

### POST /goodreads/v1/quotes — 1 credit
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.

**Parameters:**
- `author_id` (string, optional) — Goodreads author id for quotes BY that author. Supply `author_id`, OR `work_id` (book), OR a full `url`.
- `work_id` (string, optional) — Goodreads WORK id (from book_detail.book.work_id) for quotes FROM that book. Supply `work_id`, OR `author_id`, OR a full `url`.
- `url` (string, optional) — Full Goodreads quotes URL (/author/quotes/<id> or /work/quotes/<id>) — an alternative to author_id / work_id.
- `page` (integer, optional, default 1) — 1-based page number. Use meta.has_more / data.has_more to know when to stop; values < 1 clamp to 1.
- `include_pii` (boolean, optional, default false) — If true, do NOT redact reviewer display data (default redacts phone/email, keeps public name).

**Returns:** quotes[] (text, author, title, likes, tags), scope, count, page, has_more

**Example request body:**
```json
{
  "author_id": "153394"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=goodreads
- Human docs page: https://reefapi.com/docs/goodreads
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt