# Douban 豆瓣 Scraper - Movies, Ratings, Comments & Reviews (`clover_folktale/douban-scraper`) Actor

Scrape Douban (豆瓣), the Chinese site often called China's IMDb: recent hot movie and TV lists with scores, short comments with ratings and likes, full subject details (cast, genres, release dates, IMDb ID) and full review text. No login or cookies needed. Export to JSON, CSV or Excel.

- **URL**: https://apify.com/clover_folktale/douban-scraper.md
- **Developed by:** [Silkline](https://apify.com/clover_folktale) (community)
- **Categories:** Social media, Lead generation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.75 / 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/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 豆瓣 Scraper collects public movie and TV data from Douban (豆瓣) and returns clean, flat JSON. You get four kinds of data: the recent hot movie and TV lists with scores, the short comments under any film or series, full subject details such as cast, genres, release dates and IMDb ID, and the full text of long reviews. It is made for researchers, analysts, data teams and developers who need Chinese audience opinions and film metadata. No Douban account, API keys, proxies or cookies are needed.

### What is Douban?

Douban (豆瓣) is a Chinese website where people rate, comment on and review films, TV series, books and music. Its movie section, movie.douban.com, is often described as China's IMDb: every film or series has a score out of 10, short comments and long reviews written by users. This Actor covers the movie and TV part of Douban. It is an independent tool and is not affiliated with Douban.

### What data can you get?

The Actor has four modes. Every record has a `type` field that tells you what it is: `title`, `comment`, `subject` or `review`. The tables below list the fields of each record type, the most useful ones first.

#### Recent hot movies or TV (mode `hot`, `type: "title"`)

| Field | Description |
|---|---|
| `rank` | Position in the recent-hot list |
| `title` | Title of the film or series |
| `rating` | Douban score out of 10 |
| `ratingCount` | Number of ratings on Douban |
| `summary` | Douban's one-line summary: year / country / genres / director / main cast |
| `episodesInfo` | Episode info such as 47集全; empty for films |
| `isNew` | True for titles flagged as new |
| `kind` | `movie` or `tv` |
| `subjectId` | Douban subject ID of the film or series |
| `url` | Link to the subject page on douban.com |
| `posterUrl` | Poster image URL |
| `posterLargeUrl` | Larger poster image URL |

#### Short comments (mode `comments`, `type: "comment"`)

| Field | Description |
|---|---|
| `content` | Comment text |
| `ratingText` | The commenter's rating word: 力荐, 推荐, 还行, 较差 or 很差 |
| `stars` | The same rating as 1-5 stars (力荐 = 5, 很差 = 1) |
| `likeCount` | Number of people who found the comment useful |
| `location` | IP location of the commenter; empty for many comments |
| `userName` | Public display name of the commenter |
| `avatarUrl` | Avatar URL of the commenter |
| `commentId` | Comment ID |
| `subjectId` | Douban subject ID of the film or series the comment belongs to |
| `time` | Time the comment was written; empty for comments |

Comments come in Douban's popular order, most useful first.

#### Subject details (mode `subject`, `type: "subject"`)

| Field | Description |
|---|---|
| `title` | Title of the film or series |
| `year` | Release year |
| `rating` | Douban score out of 10 |
| `ratingCount` | Number of ratings on Douban |
| `genres` | List of genres |
| `directors` | List of directors |
| `writers` | List of writers |
| `cast` | Main cast in billing order (Douban cuts long lists) |
| `regions` | Countries or regions |
| `languages` | Languages |
| `releaseDates` | Release dates with the festival or region in brackets |
| `duration` | Running time as Douban shows it, e.g. 142分钟 |
| `durationMinutes` | Running time in minutes |
| `episodes` | Number of episodes; empty for films |
| `aliases` | Other titles |
| `imdbId` | IMDb ID |
| `posterUrl` | Poster image URL |
| `subjectId` | Douban subject ID |
| `url` | Link to the subject page on douban.com |

#### Review full text (mode `review`, `type: "review"`)

| Field | Description |
|---|---|
| `content` | Full text of the review |
| `title` | Title of the review |
| `ratingText` | The reviewer's rating word: 力荐, 推荐, 还行, 较差 or 很差 |
| `stars` | The same rating as 1-5 stars (力荐 = 5, 很差 = 1) |
| `userName` | Public display name of the reviewer |
| `time` | Time the review was written |
| `forwardCount` | Times the review was forwarded |
| `collectCount` | Times the review was saved |
| `reviewId` | Review ID |
| `url` | Link to the review page on douban.com |

The rating words mean roughly: 力荐 = strongly recommend, 推荐 = recommend, 还行 = OK, 较差 = poor, 很差 = very poor. The `stars` field turns them into a number so you can sort and average them.

### How to use Douban 豆瓣 Scraper

1. Open Douban 豆瓣 Scraper on Apify Store and go to the Input tab.
2. Choose a **Mode**: recent hot movies or TV, short comments of subjects, subject details, or review full text.
3. Fill in the input for that mode: pick movies or TV series for the hot list, paste Douban subject links or IDs for comments and subject details, or paste Douban review links or IDs for reviews.
4. Set **Max results**, the total number of items you want from the run.
5. Click **Start**. With an empty input (`{}`) the Actor lists the 20 recent hot movies, so you can test it in seconds.
6. Open the dataset when the run finishes. It has ready-made views (Hot titles, Comments, Subjects, Reviews). Export it as JSON, CSV or Excel, or read it through the API.

### Input

All fields are optional. You can paste Douban links as they are; there is no need to dig out the ID.

| Field | Type | Required | What it does | Default |
|---|---|---|---|---|
| `mode` | string | Optional | What to scrape: `hot` (recent hot list), `comments` (short comments of subjects), `subject` (subject details) or `review` (review full text) | `hot` |
| `hotKind` | string | Optional | Mode `hot`: `movie` for recent hot movies or `tv` for recent hot TV series | `movie` |
| `subjects` | array of strings | Optional (needed for modes `comments` and `subject`) | Douban links (`https://movie.douban.com/subject/<id>/`) or subject IDs of films and series | none |
| `reviews` | array of strings | Optional (needed for mode `review`) | Douban review links (`https://movie.douban.com/review/<id>/`) or review IDs | none |
| `maxResults` | integer | Optional | Maximum number of items to return in total for this run (1 to 5,000). You are charged per item returned, and the run stops as soon as the number is reached | `20` |

#### Example: recent hot TV series

```json
{
  "mode": "hot",
  "hotKind": "tv",
  "maxResults": 50
}
```

#### Example: short comments of a film

```json
{
  "mode": "comments",
  "subjects": ["https://movie.douban.com/subject/1292052/"],
  "maxResults": 100
}
```

#### Example: subject details for several titles

```json
{
  "mode": "subject",
  "subjects": [
    "https://movie.douban.com/subject/1292052/",
    "38184963"
  ],
  "maxResults": 10
}
```

#### Example: full text of a review

```json
{
  "mode": "review",
  "reviews": ["https://movie.douban.com/review/10000000/"],
  "maxResults": 5
}
```

### Output example

The values below are illustrative samples, not real user data.

A hot title:

```json
{
  "type": "title",
  "kind": "movie",
  "rank": 1,
  "subjectId": "38184963",
  "url": "https://movie.douban.com/subject/38184963/",
  "title": "大学炸弹客",
  "rating": 6.4,
  "ratingCount": 1830,
  "summary": "2026 / 美国 / 剧情 惊悚 犯罪 / 雅努斯·梅兹 / 罗素·克劳 雅各布·特伦布莱",
  "episodesInfo": null,
  "isNew": false,
  "posterUrl": "https://img3.doubanio.com/view/photo/s_ratio_poster/public/p2936115679.jpg",
  "posterLargeUrl": "https://img3.doubanio.com/view/photo/m_ratio_poster/public/p2936115679.jpg"
}
```

A short comment:

```json
{
  "type": "comment",
  "commentId": "32514679",
  "subjectId": "1292052",
  "userName": "示例用户",
  "avatarUrl": "https://img3.doubanio.com/icon/u000000-1.jpg",
  "ratingText": "力荐",
  "stars": 5,
  "content": "这部电影讲的是希望和耐心，看完很久都忘不了。",
  "likeCount": 1520,
  "time": null,
  "location": "上海"
}
```

A subject:

```json
{
  "type": "subject",
  "subjectId": "1292052",
  "url": "https://movie.douban.com/subject/1292052/",
  "title": "肖申克的救赎",
  "year": 1994,
  "rating": 9.7,
  "ratingCount": 3000000,
  "genres": ["剧情", "犯罪"],
  "directors": ["弗兰克·德拉邦特"],
  "writers": ["弗兰克·德拉邦特", "斯蒂芬·金"],
  "cast": ["蒂姆·罗宾斯", "摩根·弗里曼"],
  "regions": ["美国"],
  "languages": ["英语"],
  "releaseDates": ["1994-09-10(多伦多电影节)", "1994-10-14(美国)"],
  "duration": "142分钟",
  "durationMinutes": 142,
  "episodes": null,
  "aliases": ["The Shawshank Redemption"],
  "imdbId": "tt0111161",
  "posterUrl": "https://img3.doubanio.com/view/photo/s_ratio_poster/public/p000000000.jpg"
}
```

A review:

```json
{
  "type": "review",
  "reviewId": "10000000",
  "url": "https://movie.douban.com/review/10000000/",
  "title": "一部关于希望的电影",
  "userName": "示例影评人",
  "ratingText": "推荐",
  "stars": 4,
  "time": "2024-05-12 21:30:00",
  "content": "这是一篇示例影评的全文。……",
  "forwardCount": 12,
  "collectCount": 85
}
```

### How much does it cost?

The Actor uses pay-per-event pricing. You pay only for the events below, in USD:

| Event | When it is charged | Price |
|---|---|---|
| Run start | Once per run, charged when the first request to the data source succeeds, even if that request returns nothing. In `comments` mode each subject after the first adds one more start fee, because it needs its own requests; that fee is charged before the subject's first request and is kept even if that subject then fails or returns nothing | $0.015 |
| Result | Each hot title or short comment | $0.005 |
| Subject | Each subject detail record | $0.025 |
| Review full text | Each review full text | $0.03 |

Worked examples:

- **100 comments on one film** cost $0.015 + 100 × $0.005 = **$0.515**.
- **50 hot TV series** cost $0.015 + 50 × $0.005 = **$0.265**.
- **Details for 10 subjects** cost $0.015 + 10 × $0.025 = **$0.265**.
- **Full text of 5 reviews** cost $0.015 + 5 × $0.03 = **$0.165**.

The run-start fee is charged when the first request to the data source succeeds, even if that request returns nothing. It is not charged when the data source fails from the start or rejects the IDs, or when your spending limit cannot cover it. You are never charged for items that were not delivered, and you never pay for more than `maxResults` items. The run also stops by itself if your spending limit is reached.

On the free Apify plan, a run makes only one data request and then stops with "Free plan limit reached": you get up to 20 hot titles or up to 20 comments (the first page of the first subject), but only 1 subject detail or 1 review. Any paid Apify plan removes the limit. On the free Apify plan each account can run this Actor up to 3 times per 24 hours and 10 times per 7 days, within a small lifetime free allowance shared across all our Actors, and all free accounts share a daily free budget. When any of these limits is reached, the run stops before fetching anything and nothing is charged.

### Use cases

- **Audience research**: read what Chinese viewers say about a film or series in their own words, with each comment's rating and likes.
- **Trend tracking**: see which films and series are on Douban's recent hot lists and follow how their scores and rating counts move over time.
- **Catalogue enrichment**: add Chinese titles, other titles, cast, directors, release dates and running times to a movie database or recommender, and join records with other sources through the IMDb ID.
- **China market research**: check how a film or series is received in China, including scores, comment tone and, for many comments, the IP location of the commenter.
- **Sentiment analysis and AI datasets**: build Chinese-language opinion datasets where each comment or review comes with a 1-5 star label.
- **Review analysis**: collect the full text of long reviews with forward and save counts to study which reviews get attention.

### Integrations and API

You can start runs from the Apify Console, through the Apify API, or on a schedule (for example, the hot lists every day). Results can be sent on to other tools with Apify integrations and webhooks, or downloaded as JSON, CSV or Excel. Here is a Python example using the `apify-client` package:

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_APIFY_TOKEN>")
run = client.actor("clover_folktale/douban-scraper").call(run_input={
    "mode": "comments",
    "subjects": ["https://movie.douban.com/subject/1292052/"],
    "maxResults": 100,
})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)
```

### Tips and limits

- **Request sizes:** a hot list or comment request returns 20 items; subject details and review texts are one item per request.
- **Hot list size:** the hot lists show Douban's "latest" selection. The movie list holds about 500 titles and the TV list about 250.
- **Comment order:** comments come in Douban's popular order, most useful first.
- **Stability:** the Actor retries transient errors on its own and stops cleanly instead of failing half-way.
- **Not found:** an unknown or deleted subject or review is skipped, not a failed run. If too many inputs return nothing, the run stops to protect your budget.
- **Budget:** a run stops as soon as `maxResults` is reached, and also when your spending limit is reached.
- **Free plan:** on the free Apify plan a run makes only one data request: up to 20 hot titles or comments (first page of the first subject only), but only 1 subject detail or 1 review. Any paid Apify plan removes the limit.
- **Empty fields:**
  - `time` is empty on comments; it is filled on reviews.
  - `location` (IP location) is empty on many comments.
  - `episodesInfo` and `episodes` are empty for films.
  - In subject records, `writers`, `languages` or `aliases` can be empty for less known titles.
  - `cast` lists the main cast only, because Douban cuts long lists.
- **No user IDs:** comments carry the display name and avatar but no user ID.

### FAQ

#### Do I need a Douban account, cookies or an API key?

No. You do not need a Douban account, API keys, proxies or cookies. You only need an Apify account to run the Actor.

#### Is it legal to scrape Douban?

The Actor returns only public data: what anyone sees on a Douban page, such as scores, comment text, display names and avatars. It returns no account data and no private data such as phone numbers or private messages. You are responsible for how you use the data and for following the laws and rules that apply to you.

#### How fresh is the data?

The data is collected when you run the Actor, so it reflects what Douban shows at that moment. The hot lists follow Douban's "latest" selection. Schedule runs if you want to track changes over time.

#### Why are some fields empty?

Douban does not show every field for every item. `time` is empty on comments, `location` is empty on many comments, episode fields are empty for films, and `writers`, `languages` or `aliases` can be empty for less known titles. See Tips and limits for the full list.

#### How many results can I get?

Up to 5,000 items per run, set with `maxResults`. On the free Apify plan a run makes only one data request: up to 20 hot titles or comments, but only 1 subject detail or 1 review. The hot movie list holds about 500 titles and the TV list about 250.

#### Does it cover books or music?

No. This Actor covers Douban movies and TV series: the hot lists, short comments, subject details and long reviews.

#### Can I schedule runs and export the data?

Yes. You can schedule runs in Apify, start them through the API, and export every dataset as JSON, CSV or Excel.

#### A field or filter I need is missing. What can I do?

Open an issue from the Actor page and it will be looked at.

### More tools from the same developer

- [Zhihu 知乎 Scraper - Answers, Articles, Comments & Users](https://apify.com/clover_folktale/zhihu-scraper)
- [Bilibili B站 Scraper - Videos, Comments, Subtitles & User IDs](https://apify.com/clover_folktale/bilibili-scraper)
- [Weibo 微博 Scraper - Posts, Comments, User IDs & IP Location](https://apify.com/clover_folktale/weibo-scraper)
- [Xiaohongshu 小红书 RedNote Scraper - Notes, Comments & User IP](https://apify.com/clover_folktale/xiaohongshu-scraper)
- [Douyin 抖音 Scraper - Videos, Comments, User IDs & IP Location](https://apify.com/clover_folktale/douyin-scraper)
- [WeChat Official Account 公众号 Scraper - Articles & Read Counts](https://apify.com/clover_folktale/wechat-scraper)

# Actor input Schema

## `mode` (type: `string`):

What to scrape: the recent-hot list, the short comments of subjects, the details of subjects, or the full text of reviews.

## `hotKind` (type: `string`):

Recent hot movies or recent hot TV series.

## `subjects` (type: `array`):

Douban links (https://movie.douban.com/subject/<id>/) or subject IDs of films and series.

## `reviews` (type: `array`):

Douban review links (https://movie.douban.com/review/<id>/) or review IDs.

## `maxResults` (type: `integer`):

Maximum number of items to return in total for this run. You are charged per item returned. On the free Apify plan a run returns at most 20 results in total; any paid Apify plan removes the limit.

## Actor input object example

```json
{
  "mode": "hot",
  "hotKind": "movie",
  "subjects": [
    "https://movie.douban.com/subject/1292052/"
  ],
  "reviews": [
    "https://movie.douban.com/review/10000000/"
  ],
  "maxResults": 20
}
```

# Actor output Schema

## `results` (type: `string`):

All scraped items (JSON, CSV, Excel via the dataset API).

# 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 = {
    "subjects": [
        "https://movie.douban.com/subject/1292052/"
    ],
    "reviews": [
        "https://movie.douban.com/review/10000000/"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("clover_folktale/douban-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 = {
    "subjects": ["https://movie.douban.com/subject/1292052/"],
    "reviews": ["https://movie.douban.com/review/10000000/"],
}

# Run the Actor and wait for it to finish
run = client.actor("clover_folktale/douban-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 '{
  "subjects": [
    "https://movie.douban.com/subject/1292052/"
  ],
  "reviews": [
    "https://movie.douban.com/review/10000000/"
  ]
}' |
apify call clover_folktale/douban-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,clover_folktale/douban-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/jfLKdLVj0VUW3WGiF/builds/gHz6R9crxWtceSvnm/openapi.json