# Goodreads Scraper - Books, Ratings & Reviews (`axlymxp/goodreads-scraper`) Actor

Goodreads book data and reader reviews: ratings with star distribution, genres, series, awards, ISBNs and authors, plus review text, stars, likes and reviewers. Look up by URL, ISBN, title or search; filter reviews.

- **URL**: https://apify.com/axlymxp/goodreads-scraper.md
- **Developed by:** [axly](https://apify.com/axlymxp) (community)
- **Categories:** Marketing, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Goodreads Scraper — Books, Ratings & Reviews

Get Goodreads book data and reader reviews as clean JSON, CSV or Excel. Paste Goodreads links, book ids, ISBNs or just
"title author", or search by title, author or series. For every book you get ratings with the full 1–5 star distribution,
review counts per language, description, cover, ISBN/ASIN, pages, publisher, publication dates, genres, series, awards,
characters and author details. Add written reviews with text, rating, dates, likes, shelves and reviewer, filtered by stars,
language or words mentioned, newest or most popular first, thousands per book.

Built for publishers and book marketers, authors, BookTok and book-club creators, book apps and recommendation engines, and
researchers studying reading and reviews. Goodreads closed its public API in 2020; this gives the same data back.

### What you get

**Book rows** (`type: "book"`)

| Field | Description |
| --- | --- |
| `bookId`, `url`, `title`, `titleComplete`, `originalTitle` | Goodreads id and link, title (with series), original title |
| `author`, `authorId`, `authorUrl`, `contributors` | Author and all contributors with roles (translator, narrator…) |
| `averageRating`, `ratingsCount`, `reviewsCount` | e.g. 4.51 from 1,915,068 ratings, 263,601 written reviews |
| `ratingsDistribution` | Ratings per star: `{"1": 8831, "2": 28265, "3": 139971, "4": 540708, "5": 1197293}` |
| `reviewsByLanguage` | Written reviews per language: `{"en": 235179, "es": 9410, …}` |
| `description`, `imageUrl` | Blurb and cover image |
| `genres`, `series` | Top genres/shelves, series name and position |
| `isbn`, `isbn13`, `asin`, `format`, `pages`, `publisher`, `language`, `publishedAt`, `firstPublishedAt` | Edition details and first publication |
| `awards`, `characters`, `places` | Awards (winner/nominee, category, year), characters and settings |
| `quotesCount`, `questionsCount` | Community quotes and reader questions |
| `authorBio`, `authorImageUrl`, `authorFollowers`, `authorWorksCount` | Author profile |

**Review rows** (`type: "review"`)

| Field | Description |
| --- | --- |
| `bookId`, `bookTitle` | The book reviewed |
| `rating`, `text`, `textHtml` | Stars (1–5) and review text (plain and HTML) |
| `createdAt`, `updatedAt` | UTC timestamps |
| `likes`, `comments`, `spoiler` | Engagement and spoiler flag |
| `shelves`, `readingStatus` | The reviewer's shelves/tags for the book (e.g. "favorites", "audiobook") and read status |
| `reviewerId`, `reviewerName`, `reviewerUrl`, `reviewerFollowers`, `reviewerReviewsCount`, `reviewerIsAuthor` | Reviewer profile |
| `url` | Review link |

### Use cases

- **Publishers and marketers:** track ratings and new reviews of your list and of competing titles; mine 1–2 star reviews for
  objections and 5-star reviews for quotes.
- **Authors and agents:** comparable-title research: rating distributions, review volume, genres and awards.
- **Book apps and recommendation engines:** rich metadata plus review text for embeddings and sentiment.
- **Researchers:** reading trends, review language and sentiment over time.

### Input

| Field | Description |
| --- | --- |
| `books` | Goodreads URLs, book ids, ISBNs or "title author", one per line |
| `searchQueries`, `resultsPerQuery` | Search by title, author or series and take the top N books |
| `includeReviews`, `maxReviewsPerBook` | Reviews on/off and how many per book |
| `reviewSort` | Popular (default), newest first or oldest first |
| `reviewStars` | Only these star ratings, e.g. `["1","2"]` for negative reviews |
| `reviewLanguage`, `reviewSearch` | Review language (en, es, de…) and words the review must mention |
| `maxItems` | Maximum rows in total |

#### Example: the 500 newest 1–2 star reviews of two books

```json
{
  "books": ["https://www.goodreads.com/book/show/54493401-project-hail-mary", "9781649374042"],
  "reviewStars": ["1", "2"],
  "reviewSort": "NEWEST",
  "maxReviewsPerBook": 250
}
```

#### Example: book data only for a list of ISBNs

```json
{ "books": ["9780593135204", "9781649374042", "9780439023481"], "includeReviews": false }
```

### Scheduling and integrations

Schedule a daily run with `reviewSort: "NEWEST"` to collect new reviews of your titles, and send them to Google Sheets, Slack or
your database with Apify integrations, webhooks or the API (`/v2/datasets/{id}/items?format=json|csv|xlsx`).

### Use it from AI assistants

The actor works as a tool in AI agents through the Apify MCP server (`https://mcp.apify.com`): "what do readers dislike about
Fourth Wing?" can run it with 1–2 star reviews and summarise them.

### FAQ

**How many reviews can I get?** As many as the book has; popular books have hundreds of thousands. Use `maxReviewsPerBook` to set
the limit. In tests 3,000 reviews of one book took under a minute.

**Can I search by ISBN?** Yes, ISBN-10 and ISBN-13 both work, as do Goodreads URLs, ids and "title author".

**Are ratings without text included?** No, review rows are written reviews; the book row has the total ratings count and the star
distribution.

**Is this legal?** The actor reads public Goodreads data. You are responsible for how you use it and for respecting reviewers'
privacy and Goodreads' terms.

**Something wrong or missing?** Open an issue on the actor page. Issues are read and answered.

# Actor input Schema

## `books` (type: `array`):

One per line: Goodreads book URL (https://www.goodreads.com/book/show/54493401-project-hail-mary), book id, ISBN (9780593135204) or 'title author' (Fourth Wing Rebecca Yarros).

## `searchQueries` (type: `array`):

Search Goodreads by title, author or series; the top results of each query are scraped.

## `resultsPerQuery` (type: `integer`):

How many search results to take per query.

## `includeReviews` (type: `boolean`):

Also scrape written reviews of each book (one row per review).

## `maxReviewsPerBook` (type: `integer`):

Reviews to collect per book (popular books have hundreds of thousands).

## `reviewSort` (type: `string`):

Order of reviews.

## `reviewStars` (type: `array`):

Only reviews with these star ratings (a continuous range, e.g. 1 and 2 for negative reviews). Empty = all.

## `reviewLanguage` (type: `string`):

ISO code (en, es, de, fr, pt, pl…) or language name. Empty = all languages.

## `reviewSearch` (type: `string`):

Only reviews containing this text (Goodreads' own review search).

## `maxItems` (type: `integer`):

Maximum rows in total (books + reviews).

## `proxyConfiguration` (type: `object`):

Not needed. Set one only if your runs get blocked.

## Actor input object example

```json
{
  "books": [
    "https://www.goodreads.com/book/show/54493401-project-hail-mary",
    "9781649374042"
  ],
  "resultsPerQuery": 5,
  "includeReviews": true,
  "maxReviewsPerBook": 30,
  "reviewSort": "DEFAULT",
  "maxItems": 100,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "books": [
        "https://www.goodreads.com/book/show/54493401-project-hail-mary",
        "9781649374042"
    ],
    "maxReviewsPerBook": 30,
    "maxItems": 100,
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("axlymxp/goodreads-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "books": [
        "https://www.goodreads.com/book/show/54493401-project-hail-mary",
        "9781649374042",
    ],
    "maxReviewsPerBook": 30,
    "maxItems": 100,
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("axlymxp/goodreads-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "books": [
    "https://www.goodreads.com/book/show/54493401-project-hail-mary",
    "9781649374042"
  ],
  "maxReviewsPerBook": 30,
  "maxItems": 100,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call axlymxp/goodreads-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,axlymxp/goodreads-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/rthhtfAE3t46Xf2NE/builds/94JOXaJw7RBoOwMP4/openapi.json