Goodreads Book, Author & Listopia List Scraper: MCP config, n8n workflow and API

{
  "mode": "isbns",
  "bookUrls": [
    "https://www.goodreads.com/book/show/4671.The_Great_Gatsby"
  ],
  "isbns": [
    "9780743273565"
  ],
  "maxItems": 1,
  "detailLevel": "full",
  "includeMetadata": false,
  "includeRelated": false,
  "maxReviewsPerBook": 3,
  "reviewSort": "DEFAULT",
  "reviewLanguage": "all",
  "excludeSpoilers": false,
  "maxEditionsPerBook": 3,
  "quoteTags": [
    "love"
  ],
  "maxQuotesPerSource": 3,
  "maxSimilarPerBook": 5,
  "maxListsPerBook": 5,
  "releaseYear": 2026,
  "releaseMonth": "all"
}

---
name: goodreads-book-author-and-listopia-list-scraper
description: "One dataset of Goodreads records identified by recordType: books, reviews, editions, quotes, authors, series, Listopia lists, listing rows, and release-chart entries. Runs the Apify Actor dataspryva/goodreads-book-author-and-listopia-list-scraper. Use when the user needs Goodreads data with fields such as recordType, title, primaryAuthor, averageRating, ratingsCount, publishedYear and an Apify token is available."
compatibility: "Needs network access, curl, and an APIFY_TOKEN environment variable. Runs are billed to the token owner's Apify account."
metadata:
  actor: "dataspryva/goodreads-book-author-and-listopia-list-scraper"
  store-url: "https://apify.com/dataspryva/goodreads-book-author-and-listopia-list-scraper"
---

# Goodreads Book, Author & Listopia List Scraper

Use this skill to fetch Goodreads data with the Apify Actor `dataspryva/goodreads-book-author-and-listopia-list-scraper` and work with the returned rows.

## Before running

1. Check that `APIFY_TOKEN` is set in the environment. Never print it or write it to a file.
2. Build `input.json` from the user's request using the fields below. Keep limits small for a first run.
3. Confirm the search terms or URLs with the user if the request is ambiguous.

## Input fields

| Field | Type | Meaning |
| --- | --- | --- |
| `mode` | string, required | What to scrape. Auto runs every non-empty input you provide. |
| `bookUrls` | array | Goodreads book URLs, bare book IDs, or ISBNs. Used by books, reviews, editions, similar, and bookLists. (mode=books, reviews, editions, similar, bookLists, auto) |
| `searchQueries` | array | Titles, authors, or keywords to search for. (mode=search, auto) |
| `isbns` | array | ISBN-10 or ISBN-13 values. Hyphens and spaces are accepted. (mode=isbns, auto) |
| `authorUrls` | array | Goodreads author URLs or bare author IDs. (mode=authors, auto) |
| `seriesUrls` | array | Goodreads series URLs or bare series IDs. (mode=series, auto) |
| `listUrls` | array | Listopia /list/show/ URLs or bare list IDs. (mode=lists, auto) |
| `shelfNames` | array | Popular shelf names such as mystery, fantasy, or historical-fiction. (mode=shelves, auto) |
| `genreNames` | array | Genre slugs such as fantasy, romance, or science-fiction. (mode=genres, auto) |
| `maxItems` | integer | Hard cap on every record emitted in the run, including review, edition, quote, list, and summary records. |
| `detailLevel` | one of `full`, `listing` | Full returns complete book records. Listing returns lighter row records for search, author, series, list, shelf, and genre results. |
| `includeMetadata` | boolean | Also emit one author, series, or Listopia summary record alongside the books. |
| `includeRelated` | boolean | In auto mode, also collect reviews, editions, similar books, and lists for each book URL. |
| `maxReviewsPerBook` | integer | Reviews to collect for each book. (mode=reviews) |

Example `input.json` (the Actor's published prefill):

```json
{
  "mode": "isbns",
  "bookUrls": [
    "https://www.goodreads.com/book/show/4671.The_Great_Gatsby"
  ],
  "isbns": [
    "9780743273565"
  ],
  "maxItems": 1,
  "detailLevel": "full",
  "includeMetadata": false,
  "includeRelated": false,
  "maxReviewsPerBook": 3,
  "reviewSort": "DEFAULT",
  "reviewLanguage": "all",
  "excludeSpoilers": false,
  "maxEditionsPerBook": 3,
  "quoteTags": [
    "love"
  ],
  "maxQuotesPerSource": 3,
  "maxSimilarPerBook": 5,
  "maxListsPerBook": 5,
  "releaseYear": 2026,
  "releaseMonth": "all"
}
```

## Run

```bash
curl -sS -X POST "https://api.apify.com/v2/acts/dataspryva~goodreads-book-author-and-listopia-list-scraper/run-sync-get-dataset-items" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d @input.json > results.json
```

The call waits for the run to finish and returns the dataset items as a JSON array. If the run needs more than 300 seconds the API answers with HTTP 408; then start the run with `POST /v2/acts/dataspryva~goodreads-book-author-and-listopia-list-scraper/runs`, poll `GET /v2/actor-runs/{runId}` until `SUCCEEDED`, and read `GET /v2/datasets/{defaultDatasetId}/items`.

## Output

Each item is one record. Published fields include: `recordType`, `title`, `primaryAuthor`, `averageRating`, `ratingsCount`, `publishedYear`, `url`, `bookId`, `rating`, `reviewer.name`, `createdAt`, `likesCount`, `reviewText`.

Summarise what was found, cite the record URLs when present, and say how many items came back. Do not invent values for empty fields.