# Goodreads (/docs/goodreads)

Search Goodreads books, read reviews, authors, quotes, series and Listopia lists as structured JSON

Goodreads is where readers rate and review books. These endpoints return book records, reader reviews, authors, quotes, series and Listopia lists. Reviews use the same canonical `Review` shape as Amazon, Trustpilot and Tripadvisor, so one parser reads them all.

Base URL: `/v1/goodreads/...`

Goodreads exposes 10 routes here. Book routes take exactly one of `id`, `url` or `isbn`. Author routes take `id` or `url`.

## Quickstart

### Find the book

Search by title, author or keyword and read the book `id` off the result.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/goodreads/search?query=the%20hobbit" \
  -H "x-api-key: YOUR_API_KEY"
```

### Read the book in full

This returns the average rating, the 1 to 5 star breakdown, rating and review counts, review counts by language, and genres. Add `include_similar=true` or `include_lists=true` for similar books and Listopia lists.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/goodreads/book?id=5907" \
  -H "x-api-key: YOUR_API_KEY"
```

### Page through the reviews

Reviews come 30 a page. Sort by `popular`, `newest` or `oldest`, and filter by `rating` (1 to 5), `language` or a `search` phrase. Pass the returned `cursor` for the next page.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/goodreads/book/reviews?id=5907&sort=newest&rating=5" \
  -H "x-api-key: YOUR_API_KEY"
```

## Authors, quotes, series and lists

`author` returns the profile and `author/books` lists the books, sorted by `popular`, `title`, `newest`, `rating` or `pages`. `quotes` takes exactly one of `book`, `author`, `tag` or `query`. `series` returns a whole series in reading order in a single call. `lists` returns the books on one Listopia list when you pass `id` or `url`, and the lists for a tag when you pass `tag`.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/goodreads/author/books?id=656983&sort=popular" \
  -H "x-api-key: YOUR_API_KEY"
```

## All endpoints

## Platform notes

**Reviews cost more than the other routes.** Book reviews are 5 credits a page of 30. Every other Goodreads route is 1 credit.

**Comments hang off a review.** `GET /v1/goodreads/review/comments` takes the `id` exactly as `review.id` appears on the book reviews route, including its `kca://` prefix.

**Language codes come from the book.** `GET /v1/goodreads/book` lists the languages a book has reviews in. Pass one of them, such as `en`, `es`, `de` or `zh-TW`, as `language` on the reviews route.

**Series are not paged.** A series comes back whole, so there is no `cursor` on that route.

For product-level opinion on the same titles, compare with [Amazon](/docs/amazon.md) reviews.

## Next steps

- [Credits](/docs/credits.md): What each tier costs, and which failures are refunded.
- [Pagination](/docs/pagination.md): How cursors work across list endpoints.
- [Trustpilot](/docs/trustpilot.md): Company reviews in the same review shape.