# Goodreads Scraper - Search, Books, Genres & Authors (`one_house/goodreads-scraper`) Actor

Scrape Goodreads book search results, book details (ratings, ISBN, genres, series, sample reviews), genre/shelf listings, and author profiles & bibliographies.

- **URL**: https://apify.com/one\_house/goodreads-scraper.md
- **Developed by:** [One House](https://apify.com/one_house) (community)
- **Categories:** Integrations, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 book details

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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

Goodreads Scraper is an all-in-one **[Goodreads](https://www.goodreads.com/)** scraper that extracts book search results, full book details, genre/shelf listings, and author profiles & bibliographies — all from one Actor. Just paste any Goodreads URL, a search term, or a genre name and the Actor figures out what kind of page it is and scrapes the right data. Run it on demand, on a schedule, or through the API — with automatic proxy rotation and structured JSON/CSV/Excel output.

### What does Goodreads Scraper do?

This Actor covers the five most common ways people browse Goodreads:

- **Search** — book title, author, or ISBN → ranked list of matching books with ratings.
- **Book detail** — full metadata for a single book: description, ISBN/ISBN-13, page count, publisher, genres, series, awards, characters, places, rating breakdown, and a sample of real reviews.
- **Genre / shelf** — the top books Goodreads shelves under a genre tag (e.g. `science-fiction`, `historical-romance`).
- **Author profile** — bio, birth/death dates, website, follower count, and aggregate rating across all their books.
- **Author bibliography** — the author's full, paginated list of books.

You don't need to pick a "mode" — every URL you provide is automatically classified and routed to the right parser.

### Why use Goodreads Scraper?

- **Market & competitive research** — track how a book, genre, or author is trending in ratings and review volume.
- **Publishing & marketing** — build catalogs, compare editions, or monitor a backlist author's bibliography.
- **Recommendation & content apps** — bulk-import book metadata, genres, and series data.
- **Academic / NLP research** — collect review text samples at scale for sentiment or literary analysis.

Running it on Apify gets you proxy rotation, scheduling, webhooks, and API access out of the box — no need to maintain your own scraping infrastructure or handle Goodreads' HTML changes yourself.

### How to use Goodreads Scraper

1. Click **Try for free** (or **Start**) on the Actor page.
2. Under **Goodreads URLs**, paste one or more links — a search results page, a book page, an author page, an author's book-list page, or a genre/shelf page. You can also use the **Search queries** or **Genres** fields instead of building URLs by hand.
3. Adjust the optional limits (pages per search, pages per bibliography, reviews per book) if needed.
4. Click **Start** and watch the run — results stream into the **Dataset** tab as they're scraped.
5. Export the dataset as JSON, CSV, Excel, HTML, or XML, or pull it via the API/integration of your choice.

### Input

| Field                | Type             | Description                                               |
| -------------------- | ---------------- | --------------------------------------------------------- |
| `startUrls`          | array            | Any Goodreads URLs; page type is auto-detected.           |
| `searchQueries`      | array of strings | Plain-text search terms, alternative to search URLs.      |
| `genres`             | array of strings | Genre/shelf slugs, e.g. `science-fiction`.                |
| `maxSearchPages`     | integer          | Max result pages per search (0 = all). Default `3`.       |
| `includeAuthorBooks` | boolean          | Also crawl an author's full bibliography. Default `true`. |
| `maxAuthorBookPages` | integer          | Max bibliography pages per author (0 = all). Default `0`. |
| `maxReviews`         | integer          | Sample reviews to include per book (0–30). Default `10`.  |
| `proxyConfiguration` | object           | Optional Apify Proxy.                                     |

See the **Input** tab for the full schema with defaults and examples.

### Output

Every dataset item has a `type` field (`search_result`, `book`, `genre_book`, `author`, `author_book`) so you can filter or split the dataset by page type. Example — a book detail item:

```json
{
    "type": "book",
    "bookId": 44767458,
    "title": "Dune",
    "titleComplete": "Dune (Dune, #1)",
    "url": "https://www.goodreads.com/book/show/44767458-dune",
    "description": "Set on the desert planet Arrakis, Dune is the story of...",
    "author": "Frank Herbert",
    "authorUrl": "https://www.goodreads.com/author/show/58.Frank_Herbert",
    "isbn13": "9780593099322",
    "format": "Hardcover",
    "numPages": 658,
    "publisher": "Ace",
    "genres": ["Science Fiction", "Fiction", "Fantasy", "Classics"],
    "series": [{ "name": "Dune", "url": "https://www.goodreads.com/series/45935-dune", "position": "1" }],
    "averageRating": 4.29,
    "ratingsCount": 1694671,
    "textReviewsCount": 88168,
    "reviewsSample": [
        {
            "reviewerName": "Rajat Ubhaykar",
            "rating": 5,
            "text": "In my head, the purpose of this review is...",
            "likeCount": 3018
        }
    ]
}
```

You can download the dataset in various formats such as JSON, HTML, CSV, or Excel.

#### Data table

| Field                                                           | Present on                    | Description                                                        |
| --------------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------ |
| `type`                                                          | all                           | `search_result` / `book` / `genre_book` / `author` / `author_book` |
| `bookId` / `authorId`                                           | book-related / author-related | Numeric Goodreads ID                                               |
| `title`, `url`, `coverImageUrl`                                 | search, genre, author books   | Basic listing fields                                               |
| `averageRating`, `ratingsCount`                                 | most types                    | Aggregate rating stats                                             |
| `isbn`, `isbn13`, `format`, `numPages`, `publisher`, `language` | `book`                        | Edition metadata                                                   |
| `genres`, `series`, `awards`, `characters`, `places`            | `book`                        | Classification & work metadata                                     |
| `reviewsSample`                                                 | `book`                        | Array of `{ reviewerName, rating, text, likeCount, createdAt }`    |
| `bio`, `birthDate`, `deathDate`, `website`, `followersCount`    | `author`                      | Profile fields                                                     |

### Pricing / cost estimation

Goodreads Scraper uses **Pay-Per-Event** pricing — you only pay for the records it actually returns, not for run time or compute. Lightweight list rows (search, genre, bibliography) are priced separately from the richer, more expensive-to-parse book and author records:

| Event               | Charged for                                       | Price / 1,000 |
| ------------------- | ------------------------------------------------- | ------------- |
| `search-result`     | each book row in search results                   | $0.50         |
| `genre-book`        | each book row in a genre/shelf listing            | $0.50         |
| `author-book`       | each book row in an author's bibliography         | $1.00         |
| `author-profile`    | each author profile scraped                       | $2.00         |
| `book-detail`       | each full book record (metadata + sample reviews) | $2.00         |
| `apify-actor-start` | run start (infrequent, charged once per run)      | $0.00005      |

There's no separate compute-unit charge on top — it's HTTP-only (no headless browser), so runs are fast and the event price already covers it. For example, scraping 1 book detail page, 1 author profile, and a 50-book genre listing costs roughly $0.002 + $0.002 + 50 × $0.0005 = **$0.03**.

### Tips / advanced options

- Leave `maxSearchPages` and `maxAuthorBookPages` at their defaults for quick runs; raise them (or set `0`) for exhaustive crawls.
- Set `maxReviews` to `0` if you only need metadata — it skips review parsing entirely and slightly speeds up book requests.
- Genre/shelf listings are capped at ~50 books by Goodreads itself for anonymous visitors — there is no `page` parameter or pagination control that unlocks more, with or without a proxy. If you need broader genre coverage, combine several related shelf slugs (e.g. `science-fiction`, `sci-fi-fantasy`, `space-opera`).
- Turn on Apify Proxy for large, sustained runs to reduce the chance of rate limiting.

### FAQ, disclaimers, and support

This Actor only reads publicly accessible Goodreads pages — it does not log in, does not access private shelves/lists, and does not modify any data on Goodreads. Scraping public data is generally permitted, but you are responsible for complying with Goodreads' Terms of Service and applicable law in your jurisdiction, especially for commercial use.

Found a page type this Actor doesn't handle correctly, or a field that's missing? Open an issue on the Actor's **Issues** tab. Need a custom variant (e.g. deeper review pagination, Listopia lists, quotes)? Reach out — custom development is available.

# Actor input Schema

## `startUrls` (type: `array`):

Any Goodreads URLs — the page type is auto-detected: search results (/search?q=...), a book (/book/show/...), an author profile (/author/show/...), an author's bibliography (/author/list/...), or a genre/shelf listing (/shelf/show/... or /genres/...).

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

Plain text search terms (title, author, or ISBN) — an alternative to pasting /search?q=... URLs above.

## `genres` (type: `array`):

Goodreads genre slugs to list top books for, e.g. "science-fiction" or "historical-fiction" (same as the slug in https://www.goodreads.com/shelf/show/{slug}). Goodreads only exposes the top ~50 books per genre to anonymous visitors — there is no further pagination.

## `maxSearchPages` (type: `integer`):

Maximum number of result pages (≈20 books each) to fetch per search query or search URL. Set 0 for all available pages.

## `includeAuthorBooks` (type: `boolean`):

When scraping an author profile, automatically follow through to their full bibliography (/author/list/...) as well.

## `maxAuthorBookPages` (type: `integer`):

Maximum number of bibliography pages (30 books each) to fetch per author. Set 0 for all available pages.

## `maxReviews` (type: `integer`):

Number of sample reviews (text, rating, reviewer, like count) to include with each scraped book. Goodreads embeds up to ~30 reviews on the book page itself — set 0 to skip reviews entirely.

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

Optional Apify Proxy. Goodreads pages fetch fine without a proxy for light usage; enable this for larger, sustained runs.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://www.goodreads.com/book/show/44767458-dune"
    },
    {
      "url": "https://www.goodreads.com/author/show/58.Frank_Herbert"
    }
  ],
  "searchQueries": [
    "dune frank herbert"
  ],
  "maxSearchPages": 3,
  "includeAuthorBooks": true,
  "maxAuthorBookPages": 3,
  "maxReviews": 10,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# 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 = {
    "startUrls": [
        {
            "url": "https://www.goodreads.com/book/show/44767458-dune"
        },
        {
            "url": "https://www.goodreads.com/author/show/58.Frank_Herbert"
        }
    ],
    "searchQueries": [
        "dune frank herbert"
    ],
    "maxSearchPages": 3,
    "maxAuthorBookPages": 3,
    "maxReviews": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("one_house/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 = {
    "startUrls": [
        { "url": "https://www.goodreads.com/book/show/44767458-dune" },
        { "url": "https://www.goodreads.com/author/show/58.Frank_Herbert" },
    ],
    "searchQueries": ["dune frank herbert"],
    "maxSearchPages": 3,
    "maxAuthorBookPages": 3,
    "maxReviews": 10,
}

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

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

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

```

## CLI example

```bash
echo '{
  "startUrls": [
    {
      "url": "https://www.goodreads.com/book/show/44767458-dune"
    },
    {
      "url": "https://www.goodreads.com/author/show/58.Frank_Herbert"
    }
  ],
  "searchQueries": [
    "dune frank herbert"
  ],
  "maxSearchPages": 3,
  "maxAuthorBookPages": 3,
  "maxReviews": 10
}' |
apify call one_house/goodreads-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=one_house/goodreads-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/Thfqlvw2Z5s6RnweY/builds/fvlItLPk93qvQbsLz/openapi.json