Media

Goodreads Books

Book records from Goodreads (goodreads.com book pages, optionally discovered from Listopia lists): title, author, star rating, ratings and review counts, rating distribution, summary, genres, first published date, pages, format, ISBN, series, cover image, awards, characters and places.

goodreads-booksgoodreadsbooksreviewsratingsmedia

3 rows in the dataset

Download the dataset

Get every row this scraper has collected as one CSV or JSONL file. If the data is older than maxAgeHours, the scraper is re-run with its configured settings first. The key needs the datasets:export scope.

DOWNLOAD_ID=$(curl -s -X POST "https://api.pandorlabs.com/v1/datasets/goodreads-books/downloads" \  -H "Authorization: Bearer $PANDORLABS_KEY" \  -H "Content-Type: application/json" \  -d '{"maxAgeHours":24,"format":"csv"}' | jq -r '.id')while true; do  STATUS=$(curl -s "https://api.pandorlabs.com/v1/downloads/$DOWNLOAD_ID" \    -H "Authorization: Bearer $PANDORLABS_KEY" | jq -r '.status')  [ "$STATUS" != "refreshing" ] && break  sleep 5donecurl -s "https://api.pandorlabs.com/v1/downloads/$DOWNLOAD_ID/file" \  -H "Authorization: Bearer $PANDORLABS_KEY" \  -o dataset.csv

At its current 3 rows, this download costs 1 credit when the data is fresh enough, or 2 credits when it has to be refreshed first.

The rate is 1 credit per 100 rows cached and 2 credits live, charged on the rows in the dataset when the download becomes ready. A failed refresh is not charged. The file stays downloadable for 24 hours. See pricing.

Start a run

To choose the targets yourself, send the parameters below as input. The call returns 202 with the run; the key needs the scrapers:run scope and the account a positive credit balance.

curl -X POST "https://api.pandorlabs.com/v1/scrapers/goodreads-books/runs" \  -H "Authorization: Bearer $PANDORLABS_KEY" \  -H "Content-Type: application/json" \  -d '{    "input": {      "bookIds": [        "2767052",        "4671"      ],      "listIds": [        "1.Best_Books_Ever"      ],      "maxPagesPerList": 1,      "maxBooks": 20    }  }'

A run is billed at the live rate once it finishes: 2 credits per 100 rows it collected. A run that collects nothing costs nothing.

Parameters

Every parameter is optional. Anything you leave out uses the default shown here; an unknown name or an invalid value is rejected with a 400 that lists each problem.

Targeting

bookIds
string[]
Book ids or URLs
Goodreads book ids (the number in /book/show/2767052-the-hunger-games) or full book URLs.
Default
["2767052","4671"]
Example
2767052
listIds
string[]
Listopia list ids
Optional Goodreads Listopia lists (id or URL). Every book on the fetched list pages is added after the explicit book ids.
Default
none
Example
1.Best_Books_Ever

Limits

maxPagesPerList
number
Max pages per list
A list page holds 100 books.
Default
1
Range
1 to 50
maxBooks
number
Max books per run
One page request per book; this caps the run.
Default
20
Range
1 to 2000

Advanced

requestDelayMs
number
Delay between requests (ms)
Goodreads answers bursts from one address with an AWS WAF challenge, which stops the run; keep this generous.
Default
5000
Range
300 to 30000

Input as JSON Schema

The same schema the API validates against. Use it as a tool input schema or to generate a typed client.

inputSchema

{  "type": "object",  "additionalProperties": false,  "properties": {    "bookIds": {      "type": "array",      "items": {        "type": "string"      },      "maxItems": 1000,      "title": "Book ids or URLs",      "description": "Goodreads book ids (the number in /book/show/2767052-the-hunger-games) or full book URLs.",      "default": [        "2767052",        "4671"      ],      "examples": [        "2767052"      ]    },    "listIds": {      "type": "array",      "items": {        "type": "string"      },      "maxItems": 1000,      "title": "Listopia list ids",      "description": "Optional Goodreads Listopia lists (id or URL). Every book on the fetched list pages is added after the explicit book ids.",      "default": [],      "examples": [        "1.Best_Books_Ever"      ]    },    "maxPagesPerList": {      "type": "number",      "minimum": 1,      "maximum": 50,      "title": "Max pages per list",      "description": "A list page holds 100 books.",      "default": 1    },    "maxBooks": {      "type": "number",      "minimum": 1,      "maximum": 2000,      "title": "Max books per run",      "description": "One page request per book; this caps the run.",      "default": 20    },    "requestDelayMs": {      "type": "number",      "minimum": 300,      "maximum": 30000,      "title": "Delay between requests (ms)",      "description": "Goodreads answers bursts from one address with an AWS WAF challenge, which stops the run; keep this generous.",      "default": 5000    }  }}

Run, poll, read rows

The run is asynchronous. Poll it until it reaches a terminal status and its billing is paid, then page through its rows. Until then the rows endpoint answers 409 (still queued or running) or 402 (payment required).

RUN_ID=$(curl -s -X POST "https://api.pandorlabs.com/v1/scrapers/goodreads-books/runs" \  -H "Authorization: Bearer $PANDORLABS_KEY" \  -H "Content-Type: application/json" \  -d '{    "input": {      "bookIds": [        "2767052",        "4671"      ],      "listIds": [        "1.Best_Books_Ever"      ],      "maxPagesPerList": 1,      "maxBooks": 20    }  }' | jq -r '.id')while true; do  RUN=$(curl -s "https://api.pandorlabs.com/v1/runs/$RUN_ID" \    -H "Authorization: Bearer $PANDORLABS_KEY")  STATUS=$(echo "$RUN" | jq -r '.status')  BILLING=$(echo "$RUN" | jq -r '.billing.status')  case "$STATUS" in queued|running) ;; *) [ "$BILLING" != "pending" ] && break ;; esac  sleep 5doneecho "$RUN" | jq '{status, rowCount, billing}'curl -s "https://api.pandorlabs.com/v1/runs/$RUN_ID/rows?page=1&limit=100" \  -H "Authorization: Bearer $PANDORLABS_KEY"

See the API reference for pagination, cancelling and listing runs.

Output fields

Rows have no fixed schema; these are the fields observed in the rows collected so far. Coverage is the share of rows where the field is present.

Field	Type	Coverage
asin	string	100%
author	string	100%
author_id	string	100%
awards	array	100%
book_id	string	100%
characters	array	100%
contributors	array	100%
cover_image	string	100%
first_published	date	100%
format	string	100%
genres	array	100%
isbn	string	100%
isbn13	string	100%
kca_id	string	100%
language	string	100%
name	string	100%
num_pages	number	100%
num_ratings	number	100%
num_reviews	number	100%
original_title	string	100%
places	array	100%
published	date	100%
publisher	string	100%
rating_distribution	array	100%
series_name	string	67%
series_position	string	67%
star_rating	number	100%
summary	string	100%
title_complete	string	100%
work_id	string	100%
created_at	date	100%
updated_at	date	100%
_id	string	100%