# Goodreads Book Details Scraper (`parseforge/goodreads-book-details-scraper`) Actor

Extract book details from Goodreads list pages and search results. Pulls title, author, cover image, and genre for each book. Ideal for building a curated book catalog or tracking reading trends. Start from a popular list like 'Best Books Ever' or search by keyword to collect data for analysis.

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

## Pricing

from $3.62 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

[![ParseForge](https://raw.githubusercontent.com/ParseForge/apify-assets/main/banner.jpg)](https://apify.com/parseforge?fpr=vmoqkp)

> **Unofficial.** This Actor is not affiliated with, endorsed by, or sponsored by Goodreads, Inc. It collects publicly available data only.

Scrapes book metadata from Goodreads list pages and search results. It collects dozens of fields per book (title, author, rating, genres, etc.) using only the public HTML pages, with no authentication required.

The actor can scrape books from any Goodreads list or shelf by providing one or more start URLs. Alternatively, you can enter a search query to find books matching a keyword; when a search query is provided, it overrides the start URLs. You can set a maximum number of items to collect - free users get a preview of up to 10 books, while paid users can collect up to 1,000,000 books. The actor automatically paginates through list pages and search results to gather all available books within the limit.

[**Open the input and run it**](https://apify.com/parseforge/goodreads-book-details-scraper/input?fpr=vmoqkp). Paste a Goodreads list URL or enter a search term, set the maximum number of books you need, and the actor starts collecting data in seconds.

| Target Audience | Primary Use Cases |
|---|---|
| Authors, publishers, librarians, book reviewers, data analysts, researchers | Discover trending books, analyze genre trends, build book recommendation systems, compile reading lists, monitor new releases |

Jump to: [Data fields](#goodreads-data-fields) · [How to scrape](#how-to-scrape-goodreads) · [Use cases](#goodreads-data-use-cases) · [API](#use-this-goodreads-scraper-as-an-api) · [Troubleshooting](#troubleshooting) · [FAQ](#goodreads-scraper-faq)

***

### What the Goodreads Book Details Scraper does

- **List scraping**: Provide one or more Goodreads list or shelf URLs to scrape all books from those pages, including pagination.
- **Search scraping**: Enter a search query to find books by keyword, title, author, or genre. This mode overrides start URLs.

***

### Goodreads Data Fields

Export to CSV, Excel, JSON or XML from the Dataset tab, or pull them straight from the API.

| Field group | Included data |
|---|---|
| Identity | `bookId`, `url` |
| Content | `title` |
| Author and source | `author` |
| Media | `imageUrl` |
| Time | `scrapedAt` |
| Other | `error` |

#### Sample record

```json
{
  "imageUrl": "https://i.gr-assets.com/images/S/compressed.photo.goodreads.com/books/1586722975i/2767052._SX50_.jpg",
  "bookId": "2767052",
  "title": "The Hunger Games (The Hunge...",
  "author": "Suzanne Collins",
  "url": "https://www.goodreads.com/book/show/2767052-the-hunger-games",
  "scrapedAt": "2026-08-10T03:23:28.124Z"
}
```

Abridged to the fields most people use.

***

### What this Goodreads scraper does not do

- **Only works with public pages.** The actor cannot access private or restricted content, and does not log in to Goodreads.
- **Search query cannot be combined with list URLs.** If you provide a search query, it ignores start URLs. You must run separate runs for different modes.
- **Rate limiting may apply.** Goodreads may throttle requests if you scrape too aggressively. The actor includes built-in delays, but very large collections (millions) may take time.
- **Not all fields are available on every page.** Some fields like ISBN, page count, or full description require visiting individual book detail pages, which this actor does not scrape. It only scrapes list and search result pages.
- **Free tier limited to 10 items.** To get more than 10 books, you need a paid Apify subscription.

***

### Why choose this Goodreads scraper

|  | Capability |
|---|---|
| Book ID | Unique identifier on Goodreads |
| Title | Full book title |
| Author | Author name(s) |
| Rating | Average rating (1-5) |
| Genres | List of genres assigned to the book |

***

### How to Scrape Goodreads

1. **Sign up.** [Create a free Apify account with $5 in credit](https://console.apify.com/sign-up?fpr=vmoqkp).
2. **Open the Actor.** Go to the [Goodreads Book Details Scraper](https://apify.com/parseforge/goodreads-book-details-scraper?fpr=vmoqkp) page.
3. **Set your input.** Paste a Goodreads list URL or enter a search term, set the maximum number of books you need, and the actor starts collecting data in seconds.
4. **Run it, then download.** Results appear in the Dataset tab as CSV, Excel, JSON or XML.

**A first run with the defaults**

```json
{
  "startUrls": [
    {
      "url": "https://www.goodreads.com/list/show/1.Best_Books_Ever"
    }
  ],
  "maxItems": 10
}
```

**A larger pull**

```json
{
  "startUrls": [
    {
      "url": "https://www.goodreads.com/list/show/1.Best_Books_Ever"
    }
  ],
  "maxItems": 200
}
```

***

### Goodreads Data Use Cases

#### Discover trending books in a genre

A book blogger wants to find the most popular books in the science fiction genre. They enter the URL of the 'Best Science Fiction' list on Goodreads, set maxItems to 100, and run the actor. They receive a dataset with titles, authors, ratings, and genres. The decision it supports: Selecting which books to review next.

#### Analyze genre trends over time

A marketing analyst needs to see which genres are gaining popularity. They use the search query '2024' and collect up to 10,000 books. They analyze the genre distribution from the output. The decision it supports: Deciding which genres to promote in a publishing campaign.

#### Build a book recommendation system

A developer building a recommendation engine needs a large dataset of book metadata. They scrape multiple Goodreads list URLs (e.g., 'Best Books Ever', 'Most Read Books') with maxItems set to 500,000. The dataset includes book IDs, titles, authors, and genres. The decision it supports: Training a collaborative filtering model to suggest books to users.

#### Compile a reading list for a book club

A book club organizer wants a list of acclaimed novels from the 20th century. They search for '20th century classics' and set maxItems to 50. The actor returns titles, authors, and ratings. The decision it supports: Choosing the next book club selection.

***

### Beyond business use cases

- **Research.** Analyze reading habits and book popularity across different lists and time periods.
- **Journalism.** Investigate genre trends, author diversity, and rating distributions for articles.
- **Public interest.** Create open datasets of book metadata for libraries and educational nonprofits.
- **Side projects.** Build personal book tracking tools, reading challenges, or gift recommendation apps.

***

### Use This Goodreads Scraper as an API

Call it from anything that can send an HTTP request. This returns the dataset in the same response:

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/parseforge~goodreads-book-details-scraper/run-sync-get-dataset-items" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "startUrls": [ { "url": "https://www.goodreads.com/list/show/1.Best_Books_Ever" } ], "maxItems": 10 }'
```

`$APIFY_TOKEN` is your Apify API token, from Settings in the console. For larger jobs, start the run asynchronously and collect results with a webhook. Client libraries exist for Node.js and Python as `apify-client`, and the full reference is in the [Apify API documentation](https://docs.apify.com/api/v2).

Save a tested input as an Apify Task and attach a [schedule](https://docs.apify.com/platform/schedules) for recurring collection.

***

### Troubleshooting

**I get 0 results even though the list URL is correct.** Check that the URL is a Goodreads list or shelf page. The actor only works with list/show and shelf/show URLs. If you use a search URL, use the searchQuery input instead.

**The run stops after a few items with a 'Too Many Requests' error.** This indicates Goodreads is throttling your IP. Wait a few minutes and try again with a smaller maxItems. The actor automatically retries, but if it persists, reduce the concurrency (not adjustable in input).

**I set maxItems to 1000 but only got 100 books.** The list or search results may not contain 1000 books. The actor stops when it reaches the end of available pages. Check the total number of books on the Goodreads page.

**The output fields do not include the rating or publication year.** Some fields may be missing if the list page does not display them. For example, some shelf pages show only basic info. Try using a different list or search query that includes more details.

**I get an error 'Invalid URL' when using startUrls.** Make sure the URL starts with https://www.goodreads.com/ and points to a list or shelf page. The actor expects exact URLs, not shortened links.

**The search query returns no results even though I see results on the website.** The search query must match exactly what Goodreads expects. Try using a simpler query. Also ensure you are not using special characters. If the issue persists, use a start URL from a search results page (copy the URL from the browser).

**Something else.** Open an issue with the run ID, your input with any secrets removed, what you expected and what came back, or email parseforge@protonmail.com.

***

### Goodreads Scraper FAQ

**How many books can I scrape with the free plan?** Free users are limited to 10 items per run. This gives you a preview of the data format and structure.

**What is the maximum number of books I can scrape?** Paid users can set maxItems up to 1,000,000. However, consider that Goodreads may throttle requests, and very large runs may take a long time.

**Can I scrape book details like ISBN or page count?** No. This actor only scrapes data from list and search result pages. Fields like ISBN, page count, and full description are on individual book detail pages and are not included.

**Can I use both start URLs and a search query in the same run?** No. If you provide a search query, it overrides the start URLs. To scrape from list pages and also search, you need to run the actor twice with different inputs.

**How do I get more than 10 books?** You need a paid Apify subscription. You can then set maxItems to any number up to 1,000,000.

**Does the actor scrape all books from a list page?** Yes, it automatically paginates through the list (e.g., pages 1, 2, 3...) and scrapes all books until it reaches your maxItems limit.

**Can I scrape multiple lists at once?** Yes, you can provide multiple start URLs in the input. The actor will scrape each list sequentially.

**What fields are included in the output?** The output includes fields such as book ID, title, author, image URL, genres, rating, number of ratings, publication year, and more. The exact list is shown in the dataset preview.

**Is login required?** No. The actor uses only public HTML pages. No authentication or cookies are needed.

**How long does a run take?** It depends on the number of books and current Goodreads response times. For 10,000 books, expect a few minutes to an hour.

**Can I filter by rating or date?** No. The actor does not have filters for rating or date. You must filter the resulting dataset after scraping.

**What if I get an error about rate limiting?** The actor has built-in retries and delays. If you see too many errors, reduce maxItems or increase the delay (not configurable in input). You can also try running multiple smaller runs.

***

### Integrate with any app

Connects to any cloud service through [Apify integrations](https://apify.com/integrations):

- [Make](https://docs.apify.com/platform/integrations/make): multi-step automations
- [Zapier](https://docs.apify.com/platform/integrations/zapier): 5,000+ apps
- [Slack](https://docs.apify.com/platform/integrations/slack): run notifications
- [Airbyte](https://docs.apify.com/platform/integrations/airbyte): pipe rows into a warehouse
- [GitHub](https://docs.apify.com/platform/integrations/github): trigger runs from commits
- [Google Drive](https://docs.apify.com/platform/integrations/drive): export straight to Sheets

***

### Related Goodreads Actors

- [parseforge/google-books-scraper](https://apify.com/parseforge/parseforge/google-books-scraper?fpr=vmoqkp): Use this if you need book data from Google Books instead of Goodreads.

Browse the full [ParseForge collection](https://apify.com/parseforge?fpr=vmoqkp) for more scrapers.

***

**Need help?** [Open our contact form](https://tally.so/r/BzdKgA) or email parseforge@protonmail.com to report an issue, request a scraper, or discuss a custom data project.

# Actor input Schema

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

List of Goodreads list or shelf URLs to scrape books from.

## `searchQuery` (type: `string`):

Optional search term to find books on Goodreads. If provided, overrides start URLs.

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

Free users: Limited to 10 items (preview). Paid users: Optional, max 1,000,000

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://www.goodreads.com/list/show/1.Best_Books_Ever"
    }
  ],
  "maxItems": 10
}
```

# 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/list/show/1.Best_Books_Ever"
        }
    ],
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("parseforge/goodreads-book-details-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/list/show/1.Best_Books_Ever" }],
    "maxItems": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("parseforge/goodreads-book-details-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 '{
  "startUrls": [
    {
      "url": "https://www.goodreads.com/list/show/1.Best_Books_Ever"
    }
  ],
  "maxItems": 10
}' |
apify call parseforge/goodreads-book-details-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,parseforge/goodreads-book-details-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/V6XyTjOFKvaZeFRUj/builds/zC5fglRWjSrHcxmwO/openapi.json