# Douban Book Ratings Scraper (`mrdoe/douban-book-ratings-scraper`) Actor

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

## Pricing

from $1.00 / 1,000 book returneds

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

![Douban Book Ratings & Reviews Scraper - Douban book scraper showing rating, star breakdown and reader reviews](https://api.apify.com/v2/key-value-stores/kE36venAoVchGsE6b/records/douban-book-ratings-scraper--hero.png)

### What does Douban Book Ratings & Reviews Scraper do?

Douban Book Ratings & Reviews Scraper searches Douban's book catalog for the terms you give it, or reads the exact book URLs you provide, and returns each book's rating out of 10, total vote count, the percent of readers giving each star rating (5 down to 1), full publishing details (author, translator, publisher, publish date, ISBN, page count, binding, price) and - if you ask for them - real reader reviews with the reviewer's name, their own rating and the review text.

### Why use Douban Book Ratings & Reviews Scraper?

- Covers China's largest book-ratings community - ratings Goodreads and Amazon don't have for Chinese-language titles.
- Full publishing metadata (ISBN, publisher, pages, price) alongside the rating, not just a score.
- Star-percent breakdown (5-star down to 1-star), not only an average.
- Real reader reviews with names, per-review ratings and useful-vote counts.
- Works by search term or by exact book URL/ID - no need to find the URL yourself.
- No account or API key.

### What makes this different

Most book-data tools only cover English-language catalogs. This Actor reads Douban - the reference ratings source for Chinese-language books - and returns the same depth of detail (star breakdown, full metadata, reviews) in one structured call.

### Who can use the Douban Book Scraper and how?

- **Publishers and literary agents:** Check how a title or translation is received by Chinese readers before a licensing decision.
- **Book recommendation apps:** Pull ratings and metadata for Chinese-language catalogs you can't source from Western APIs.
- **Researchers:** Collect rating distributions and reader sentiment at scale for literary studies.
- **Translators and publishers:** Monitor reception of a specific translated edition over time.
- **Price trackers:** Track a book's listed price and edition details.
- **Content and SEO sites:** Source accurate book metadata and ratings for a Chinese-book review site.

### How it works

![Douban Book Ratings & Reviews Scraper workflow: your input, collection, output](https://api.apify.com/v2/key-value-stores/kE36venAoVchGsE6b/records/douban-book-ratings-scraper--how-it-works.png)

1. **Your input** — add search terms, exact book URLs, or both
2. **The Actor collects it** — the Actor reads Douban's book search and detail pages and (optionally) the comments page for each book
3. **Your output** — you get one row per book, with reviews nested inside if requested

### What data can you extract?

The dataset has 18 fields per row:

| Field | Type | Description |
|---|---|---|
| `title` | string | Book title. |
| `subjectId` | string | Douban's internal book ID. |
| `url` | string | The book's Douban page. |
| `rating` | number | Average rating out of 10. |
| `ratingCount` | number | Total number of ratings. |
| `author` | string | Author name. |
| `translator` | string | Translator name, when the book is a translation. |
| `publisher` | string | Publisher. |
| `publishDate` | string | Publication date as shown on Douban. |
| `isbn` | string | ISBN. |
| `pages` | number | Page count. |
| `binding` | string | Binding type, e.g. paperback or hardcover. |
| `price` | string | Listed price as shown on Douban. |
| `star5Percent` | number | Percent of ratings that gave 5 stars. |
| `star1Percent` | number | Percent of ratings that gave 1 star. |
| `description` | string | Book summary. |
| `imageUrl` | string | Cover image URL. |
| `reviews` | array | Reader reviews with reviewer name, rating, useful votes and text. |

### How to use Douban Book Ratings & Reviews Scraper

![Douban Book Ratings & Reviews Scraper input form](https://api.apify.com/v2/key-value-stores/kE36venAoVchGsE6b/records/douban-book-ratings-scraper--input.png)

1. Open the Actor and go to the **Input** tab.
2. Add one or more search terms under Search Queries, and/or exact book URLs under Book URLs.
3. Optionally set filters and a **Max results** limit.
4. Click **Start**. A default run finishes in under a minute.
5. Open the **Output** tab, then download the dataset or connect it to your tools.

### Input Parameters

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `searchQueries` | array | No | `["围城"]` | Book titles, authors or keywords to search for on Douban, e.g. 乡村医生 or a pinyin/English title. |
| `bookUrls` | array | No | `[]` | Specific Douban book page URLs (or plain subject IDs) to scrape directly - copy these straight from book.douban.com. When set, this is used instead of Search queries. |
| `maxItemsPerQuery` | integer | No | `10` | Maximum number of books to return per search query. Set to 0 for unlimited. |
| `includeDetails` | boolean | No | `true` | Fetch each book's own detail page for author, publisher, ISBN, price and the full rating breakdown, not just what the search result already shows. |
| `includeComments` | boolean | No | `false` | Also fetch each book's most useful short reviews. |
| `maxComments` | integer | No | `10` | Only used when Include reviews is on. |
| `proxyConfiguration` | object | No | `{"useApifyProxy":false}` | Optional. The data is public and works without a proxy. |

### Output Data

![Douban Book Ratings & Reviews Scraper dataset table](https://api.apify.com/v2/key-value-stores/kE36venAoVchGsE6b/records/douban-book-ratings-scraper--output.png)

Each row is one book: its Douban rating, vote count, star-percent breakdown, full publishing metadata, and - if requested - a list of real reader reviews.

![Douban Book Ratings & Reviews Scraper field map of one record](https://api.apify.com/v2/key-value-stores/kE36venAoVchGsE6b/records/douban-book-ratings-scraper--fields.png)

A real dataset item:

```json
{
  "type": "book",
  "subjectId": "11524204",
  "title": "围城",
  "url": "https://book.douban.com/subject/11524204/",
  "rating": 9.3,
  "ratingCount": 115399,
  "castInfo": "钱锺书 / 人民文学出版社 / 1991",
  "description": "《围城》是一幅栩栩如生的世井百态图，人生的酸甜苦辣千般滋味均在其中得到了淋漓尽致的体现。钱钟书先生将自己的语言天才并入极其渊博的知识，再添加上一些讽刺主义的...",
  "imageUrl": "https://img3.doubanio.com/view/subject/s/public/s11276847.jpg",
  "query": "围城",
  "author": "钱锺书",
  "translator": null,
  "publisher": "人民文学出版社",
  "producer": null,
  "publishDate": "1991-2-1",
  "isbn": "9787020090006",
  "pages": 362,
  "binding": "精装",
  "price": "39.00元",
  "originalTitle": null,
  "series": null,
  "star5Percent": 67.5,
  "star4Percent": 27.4,
  "star3Percent": 4.6,
  "star2Percent": 0.4,
  "star1Percent": 0.2,
  "summary": "《围城》是一幅栩栩如生的世井百态图，人生的酸甜苦辣千般滋味均在其中得到了淋漓尽致的体现。钱钟书先生将自己的语言天才并入极其渊博的知识，再添加上一些讽刺主义的幽默调料，以一书而定江山。《围城》显示给我们一个真正的聪明人是怎样看人生，又怎样用所有作家都必得使用的文字来表述自己的“观…",
  "reviews": [
    {
      "type": "review",
      "subjectId": "11524204",
      "commentId": "1272114856",
      "reviewerName": "江户川柯镇恶",
      "reviewerUrl": "https://www.douban.com/people/woshilixu004/",
      "rating": 4,
      "usefulVotes": 9128,
      "reviewTime": "2018-04-08 23:03:30",
      "content": "看着心累，方鸿渐就应该跟赵辛楣搞基。"
    },
    {
      "type": "review",
      "subjectId": "11524204",
      "commentId": "706763315",
      "reviewerName": "二筒",
      "reviewerUrl": "https://www.douban.com/people/ertongertong/",
      "rating": 5,
      "usefulVotes": 4093,
      "reviewTime": "2014-02-23 01:01:00",
      "content": "倒是觉得书中词句、比喻精妙，让人体会到中文之美"
    },
    {
      "type": "review",
      "subjectId": "11524204",
      "commentId": "702501983",
      "reviewerName": "成知默",
      "reviewerUrl": "https://www.douban.com/people/chengzhimo/",
      "rating": 5,
      "usefulVotes": 2859,
      "reviewTime": "2013-07-10 10:52:56",
      "content": "时隔多年重读，钟书先生的幽默、老辣、聪明、刻薄仍让人拍案激赏。无论是方鸿渐，还是孙柔嘉，抑或苏文纨，他们的寻常人生，不过就像苏小姐的爱情，起初因为“看得太名贵了，不肯随便施与”，及至遭遇现实的损耗，就只能迅速缴械、自怅自悔了，如此过了十几年，恐怕也只能借年轻人的生气来温暖自己的衰朽。深于一切语言、一切啼笑，“围城”内外，饱含对人生的讽刺和感伤。"
    }
  ],
  "scrapedAt": "2026-10-16T05:21:29.793Z"
}
```

### Usage Examples

#### Search by title

```json
{
  "searchQueries": [
    "围城"
  ],
  "maxItemsPerQuery": 10,
  "includeDetails": true,
  "includeComments": false
}
```

#### Exact book URL with reviews

```json
{
  "bookUrls": [
    "https://book.douban.com/subject/11524204/"
  ],
  "includeDetails": true,
  "includeComments": true,
  "maxComments": 10
}
```

### Tips for Best Results

- Use exact book URLs when you already know them - it skips search and is faster.
- Turn off Include Reviews if you only need the rating and metadata - it's faster and uses fewer results.
- Default is 5 results for a fast test. Set the max to 0 to return everything available.

### Known Limitations

- Douban occasionally rate-limits very large search volumes; space out very large jobs.
- Some older or less-common titles may be missing certain metadata fields (ISBN, price) if Douban itself never recorded them.

### Integrations

Run it from the Apify API, on a schedule, or from a webhook. Send results straight to Google Sheets, Make, Zapier, Slack or your own database with Apify's built-in integrations.

### Export Formats

Download the dataset as JSON, CSV, Excel, XML, HTML table or RSS from the **Output** tab or the API.

### Frequently Asked Questions

#### Does it need a Douban login?

No. The Actor reads public search, book and comments pages and needs no account or key.

#### Can I search in English?

Search works best with the Chinese title, since that's what Douban indexes, but an exact book URL always works regardless of language.

#### How many reviews can I get per book?

Up to the Max Comments value you set, taken from the book's most useful reviews as ranked by Douban.

#### Do I need an account or login?

No. The Actor reads public data and needs no account or key.

#### Am I charged for failed runs or empty results?

You are only charged for results that are actually written to the dataset.

#### Can I run it on a schedule?

Yes. Create a Task with your input and add a schedule in Apify Console. With monitor mode on, each scheduled run returns only what changed since the previous one.

### Enterprise and custom work

Need higher volumes, a custom output schema, dedicated scheduling or a no-breaking-changes commitment for a production pipeline? Open an issue on the Actor page and describe your use case. Bulk terms and custom builds are available.

### Support

Questions or a missing field? Open an issue from the **Issues** tab on this Actor's page and it will be looked at.

### Legal / Responsible Use

You are responsible for using the data in line with the source's terms and applicable law. The Actor collects publicly available data only and is not affiliated with the source.

# Actor input Schema

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

Book titles, authors or keywords to search for on Douban, e.g. 乡村医生 or a pinyin/English title.

## `bookUrls` (type: `array`):

Specific Douban book page URLs (or plain subject IDs) to scrape directly - copy these straight from book.douban.com. When set, this is used instead of Search queries.

## `maxItemsPerQuery` (type: `integer`):

Maximum number of books to return per search query. Set to 0 for unlimited.

## `includeDetails` (type: `boolean`):

Fetch each book's own detail page for author, publisher, ISBN, price and the full rating breakdown, not just what the search result already shows.

## `includeComments` (type: `boolean`):

Also fetch each book's most useful short reviews.

## `maxComments` (type: `integer`):

Only used when Include reviews is on.

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

Optional. The data is public and works without a proxy.

## Actor input object example

```json
{
  "searchQueries": [
    "围城"
  ],
  "bookUrls": [],
  "maxItemsPerQuery": 10,
  "includeDetails": true,
  "includeComments": false,
  "maxComments": 10,
  "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 = {
    "searchQueries": [
        "围城"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("mrdoe/douban-book-ratings-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 = { "searchQueries": ["围城"] }

# Run the Actor and wait for it to finish
run = client.actor("mrdoe/douban-book-ratings-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 '{
  "searchQueries": [
    "围城"
  ]
}' |
apify call mrdoe/douban-book-ratings-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,mrdoe/douban-book-ratings-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/ArWaW7Lq1WXAsAcFo/builds/4qDKsj0zbEqsdGciu/openapi.json