# Goodreads Scraper

Scrape book title, author, and ratings from Goodreads.

- Template page: [https://www.octoparse.com/template/goodreads-scraper](https://www.octoparse.com/template/goodreads-scraper)
- Categories: Reviews
- Status: `PUBLISHED`
- Run mode: `BOTH`

## Pricing

Free.

## What is an Octoparse template?

An Octoparse template is a ready-to-use scraping workflow with predefined inputs and structured outputs. Use the exact parameter keys below; do not invent parameters.

## Overview

This ready-to-use template collects structured data from listing pages, detail pages.

## Output

The current workflow extracts 11 fields, including `Keyword`, `Progress_result_count`, `Page_URL`, `Page`, `image_url`, `book_title`, `author`, `rating`, `rating_numbers`, `published_year`, `editions`.

## Use Cases

- Use structured results for research, comparison, and monitoring.
- Collect rows without building the extraction workflow from scratch.
- Combine results with other templates for downstream enrichment.
- Review a representative result before starting a large batch.

## Why Octoparse

- **No coding required:** complete Keyword (1 per line), Number of Pages and start the template in local or cloud mode.
- **Flexible export:** review and export results as CSV, Excel, or JSON.

## Input

### Keyword (1 per line)

Required. 输入书籍分类关键词 Constraints: minItems=1.

### Number of Pages

Optional. 设置采集翻页次数

## How to Use

# Goodreads Scraper

Collects structured data from Goodreads search-result pages.

**Template:** Goodreads Scraper  
**Data source:** [Goodreads](https://www.goodreads.com/)  
**Pricing:** Free of charge (no per-line fee; Octoparse plan/resource limits may apply).

## Input

Complete these fields:

- **Keyword (1 per line)** (Required) – Enter book-category or subject keywords, one per line.
- **Number of Pages** (Optional) – Number of search-result pages to process.

## Output

Each row contains these fields:

| Field | Description |
|-------|-------------|
| `Keyword` | Input keyword |
| `Progress_result_count` | Result count (may be null) |
| `Page_URL` | URL of the result page |
| `Page` | Page number |
| `image_url` | Book cover image URL |
| `book_title` | Book title |
| `author` | Author name |
| `rating` | Average rating (e.g., `4.14`) |
| `rating_numbers` | Number of ratings (e.g., `504,883`) |
| `published_year` | Year published |
| `editions` | Number of editions |

## How to Use

1. Open Goodreads Scraper, click **Try it!**.
2. Fill in **Keyword (1 per line)** and **Number of Pages**.
3. Choose local or cloud run, start the task.
4. Review exported fields (`book_title`, `Page_URL`, `rating`, etc.) and export in desired format.

## Tips

- Start with a focused keyword to easily verify the first run.
- Keep `Keyword` in the export to trace each row back to its input.

## Limitations

Results depend on what the source site exposes at run time. Fields may be empty when a source page does not provide a value. The template enforces the input limits shown above.

## Tips

Use specific, valid inputs and review a representative result before starting a large batch. Remove duplicate inputs when repeated records are not needed.

## FAQ

### What do I need to enter?

Use the exact inputs and limits listed above.

### What data does this template return?

See Output Schema below; availability can vary by source record.

### How is usage billed?

See the Pricing section above for current pricing and billing details.

## Related Templates

- [Goodreads Comments Scraper](https://www.octoparse.com/template/goodreads-comments-scraper)
- [eBay Listing Page Scraper (by keyword)](https://www.octoparse.com/template/ebay-product-list-scraper-by-keyword)
- [eBay Scraper](https://www.octoparse.com/template/ebay-scraper)
- [Google Search Scraper](https://www.octoparse.com/template/google-search-scraper)
- [Google Maps Listings Scraper (by Keywords)](https://www.octoparse.com/template/google-maps-scraper-listing-page-by-keyword)

## Input Schema

```json
{
  "title": "Goodreads Scraper input",
  "description": "Input parameters configured for the current published template version.",
  "type": "object",
  "schemaVersion": 1,
  "additionalProperties": false,
  "properties": {
    "keyword": {
      "title": "Keyword (1 per line)",
      "description": "输入书籍分类关键词",
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "x-octoparse": {
        "apiEnabled": true
      }
    },
    "number_of_Pages": {
      "title": "Number of Pages",
      "description": "设置采集翻页次数",
      "type": "integer",
      "x-octoparse": {
        "apiEnabled": true
      }
    }
  },
  "required": [
    "keyword"
  ]
}
```

## Input JSON Example

Example 1

```json
{
  "keyword": [
    "mystery"
  ],
  "number_of_Pages": 1
}
```


## Output Schema

```json
{
  "schemaVersion": 1,
  "type": "object",
  "properties": {
    "Keyword": {
      "type": "string",
      "description": ""
    },
    "Progress_result_count": {
      "type": "string",
      "description": ""
    },
    "Page_URL": {
      "type": "string",
      "description": ""
    },
    "Page": {
      "type": "string",
      "description": ""
    },
    "image_url": {
      "type": "string",
      "description": ""
    },
    "book_title": {
      "type": "string",
      "description": ""
    },
    "author": {
      "type": "string",
      "description": ""
    },
    "rating": {
      "type": "string",
      "description": ""
    },
    "rating_numbers": {
      "type": "string",
      "description": ""
    },
    "published_year": {
      "type": "string",
      "description": ""
    },
    "editions": {
      "type": "string",
      "description": ""
    }
  },
  "title": "Goodreads Scraper output",
  "description": "Initial output fields derived from the current published implementation. Field descriptions are maintained by Data Center; production field names and types should be refreshed from recent successful runs.",
  "additionalProperties": false
}
```

## Output Example

Example 1

```json
{
  "Keyword": "mystery",
  "Progress_result_count": "Page 1 of about 417936 results (0.24 seconds)",
  "Page_URL": "https://www.goodreads.com/search?utf8=%E2%9C%93&query=mystery",
  "Page": "1",
  "image_url": "https://i.gr-assets.com/images/S/compressed.photo.goodreads.com/books/1735662086i/150247395._SY75_.jpg",
  "book_title": "The Tainted Cup (Ana and Din Mysteries, #1)",
  "author": "\n\nRobert Jackson Bennett (Goodreads Author)\n\n",
  "rating": "4.29",
  "rating_numbers": " 111,185 ",
  "published_year": "2024",
  "editions": "2"
}
```

## API

`POST https://openapi.octoparse.com/api/agentTools/executeTask`

This is the OpenAPI Agent Tools `executeTask` endpoint. Authenticate with a Bearer token.

Request body:

`templateName` is the template slug; `parameters` is a JSON object string whose keys match Input Schema; `taskName`, `idempotencyKey`, and `maxCollectedRows` are optional.

Obtain a token:

```http
POST https://openapi.octoparse.com/token
Content-Type: application/json

{
  "username": "YOUR_USERNAME",
  "password": "YOUR_PASSWORD",
  "grant_type": "password"
}
```

Use `data.access_token` as `Authorization: Bearer <token>`. After starting, poll `getTaskStatus` and export with `exportData`.

```json
{
  "templateName": "goodreads-scraper",
  "taskName": "Goodreads Scraper",
  "parameters": "{\"keyword\":[\"mystery\"],\"number_of_Pages\":1}"
}
```

## Python Example

```python
import json
import requests

OPENAPI_BASE = "https://openapi.octoparse.com"
ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"

parameters = json.loads("{\"keyword\":[\"mystery\"],\"number_of_Pages\":1}")

response = requests.post(
    f"{OPENAPI_BASE}/api/agentTools/executeTask",
    headers={
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json",
    },
    json={
        "templateName": "goodreads-scraper",
        "taskName": "Goodreads Scraper",
        "parameters": json.dumps(parameters, ensure_ascii=False),
    },
    timeout=60,
)
print(response.status_code)
print(response.json())
```

## HTTP/cURL Example

```bash
curl -X POST "https://openapi.octoparse.com/api/agentTools/executeTask" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "templateName": "goodreads-scraper",
  "taskName": "Goodreads Scraper",
  "parameters": "{\"keyword\":[\"mystery\"],\"number_of_Pages\":1}"
}
JSON
```

## MCP Setup

Connect an MCP-compatible AI client to `https://mcp.octoparse.com` using browser OAuth or an Octoparse API key. Find `goodreads-scraper`, inspect its inputs, create a cloud task with the exact Input Schema keys, and export JSON results.

## Machine-readable Resources

- [Template contract](https://www.octoparse.com/templates/goodreads-scraper.json)
- [Manifest](https://www.octoparse.com/templates/goodreads-scraper-manifest.json)
