# Douban Scraper (豆瓣电影) - 短评 Comments, 影评 Reviews, Top 250 (`improved_knot_vyk/douban-scraper`) Actor

Returns Douban (豆瓣) movies, TV, books, music: rating, star split, countries, release dates; short comments (短评) and reviews (影评) with stars and helpful votes; Top 250 and now showing with country and date filters; group posts. $2/1,000 subjects or reviews, $1/1,000 comments. No login.

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

## Pricing

Pay per event

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 Scraper

Scrape **Douban** (豆瓣), China's reference site for movies, TV, books and music: ratings with the star split, the
**Top 250**, movies **now showing**, **short comments (短评)** and **long reviews (影评)** with stars and helpful votes,
subject search, and **group discussions (豆瓣小组)**. No login, no browser, no API key.
Also known as 豆瓣电影, 豆瓣读书, Douban movie scraper, Douban API, Douban reviews scraper.

### Why this Actor

- **Movie short comments (短评)**, most helpful first, with stars and helpful votes. Up to 150 per movie, TV show,
  book or album.
- **Long reviews (影评) with the full text**, stars, helpful and unhelpful votes and reply counts. Up to 40 per subject.
- **Charts in one run**: Top 250, now showing, coming soon, popular and trending movies and TV, Top 250 books, with
  country and release-date filters and a newest-first order. Comments and reviews can be added to every chart row.
- **Group discussions**: a keyword search that keeps only topics whose title really contains the keyword (Douban's
  search is fuzzy; dropped rows are free), with the topic text and replies when you want them.
- **$2 per 1,000 subjects, reviews or topics, $1 per 1,000 short comments.** Light runs (256 MB), no start fee,
  failed and filtered rows free.

### Use cases

- **Film and TV research in China**: how a title is rated, by whom and why, across the Top 250 or this week's releases.
- **Audience sentiment**: the most helpful comments and reviews of a movie, book or album, with optional sentiment.
- **Brand and product monitoring**: what Douban group members say about a brand (`group_search`), on a schedule with
  delta mode.
- **Data for AI and analytics**: long-form Chinese reviews with full text and stable JSON fields.

### Modes

| Mode | Input | What you get |
|---|---|---|
| `charts` | `charts` (+ `countries`, `releasedAfter`, `sortBy`) | One row per subject on the chart |
| `subject_details` | `subjectUrls` | Full record: rating, star split, countries, release dates, people, intro, tags |
| `subject_comments` | `subjectUrls` | Short comments, most helpful first (up to 150 each) |
| `subject_reviews` | `subjectUrls` | Long reviews with full text (up to 40 each) |
| `subject_search` | `searchQuery`, `searchType` | Movies, TV, books and music matching the query |
| `group_search` | `searchQuery` | Group topics whose title contains the keyword, newest first |
| `group_topic` | `topicUrls` | Topic text with its replies |

Add `includeComments`, `includeReviews` or `includeDetails` to charts, details and search to get everything in one run.

#### Examples

The 5 newest Chinese movies now showing, with their 10 most helpful reviews each:

```json
{
    "mode": "charts",
    "charts": ["movie_showing"],
    "countries": ["中国大陆"],
    "sortBy": "newest",
    "maxResults": 5,
    "includeDetails": true,
    "includeReviews": true,
    "maxReviews": 10
}
```

Farewell My Concubine (霸王别姬) with its 100 most helpful short comments:

```json
{
    "mode": "subject_details",
    "subjectUrls": ["https://movie.douban.com/subject/1291546/"],
    "includeComments": true,
    "maxComments": 100
}
```

The whole Top 250: `{"mode": "charts", "charts": ["movie_top250"], "maxResults": 250}` (about 6 seconds).

### Output examples

#### Subject

```json
{
    "type": "subject",
    "subjectId": "1291546",
    "subjectType": "movie",
    "title": "霸王别姬",
    "aka": ["再见，我的妾", "Farewell My Concubine"],
    "year": "1993",
    "url": "https://movie.douban.com/subject/1291546/",
    "rating": 9.6,
    "ratingCount": 2459528,
    "starDistribution": {"1": 0.2, "2": 0.2, "3": 2.0, "4": 15.3, "5": 82.3},
    "doneCount": 4304193,
    "genres": ["剧情", "爱情", "同性"],
    "countries": ["中国大陆", "中国香港"],
    "languages": ["汉语普通话"],
    "releaseDates": ["1993-07-26(中国大陆)"],
    "releaseDate": "1993-07-26",
    "directors": ["陈凯歌"],
    "actors": ["张国荣", "张丰毅", "巩俐"]
}
```

#### Short comment

```json
{
    "type": "comment",
    "commentId": "24303417",
    "subjectId": "1291546",
    "text": "陈凯歌可以靠它吃两辈子饭了，现在看来江郎才尽也情有可原",
    "stars": 5,
    "usefulVotes": 42004,
    "status": "done",
    "createdAt": "2007-11-21T20:38:33+08:00",
    "userName": "momo"
}
```

#### Review

```json
{
    "type": "review",
    "reviewId": "1380398",
    "subjectId": "1291546",
    "title": "最懂蝶衣袁四爷",
    "content": "李碧华名作《霸王别姬》，我没看过原著，只看了电影。…",
    "stars": 5,
    "usefulCount": 25952,
    "uselessCount": 1412,
    "commentsCount": 2023,
    "createdAt": "2008-05-15T11:01:55+08:00",
    "url": "https://movie.douban.com/review/1380398/"
}
```

Dates are Beijing time (+08:00), as Douban shows them. Values Douban does not send are `null`.

### Pricing

| Event | Price |
|---|---|
| `subject` | $2 per 1,000 movies, TV shows, books or albums |
| `comment` | $1 per 1,000 short comments |
| `review` | $2 per 1,000 long reviews (full text included) |
| `topic` | $2 per 1,000 group topics (replies included) |

Proxy and compute are included. You pay only for rows delivered. Set a maximum total charge on the run to cap your
spend; the Actor stops cleanly when it is reached.

### FAQ

**How many comments and reviews can I get?** Douban shows logged-out visitors the 150 most helpful short comments and
the 40 most helpful long reviews of each subject; newest-first lists need a login. The Actor returns those, with full
review text.

**Do I need a Douban account or a proxy?** No. The Actor reads Douban's public pages without login and switches to
Apify Proxy by itself if Douban blocks a request.

**Which personal data is included?** Only what Douban shows publicly next to content: the public name and id of
commenters, reviewers and topic authors and the region Douban displays. Gender and home city are left out.

**Is it legal?** The Actor reads publicly available data without logging in. Check your local laws and Douban's terms
before using the data.

# Actor input Schema

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

One mode per run. Comments and reviews can also be added to every subject in details, charts and search.

## `charts` (type: `array`):

movie_top250, movie_showing (now showing), movie_soon, movie_hot_gaia, movie_real_time_hotest, tv_hot, tv_real_time_hotest, book_top250.

## `countries` (type: `array`):

Keep only subjects from any of these countries, as Douban writes them: 中国大陆, 中国香港, 中国台湾, 美国, 日本, 韩国...

## `releasedAfter` (type: `string`):

Keep only subjects released on or after this date: YYYY-MM-DD or YYYY.

## `sortBy` (type: `string`):

With filters, e.g. the 5 newest Chinese movies now showing: countries 中国大陆, order newest, max 5.

## `subjectUrls` (type: `array`):

Douban links like https://movie.douban.com/subject/1291546/, https://book.douban.com/subject/1084336/, https://music.douban.com/subject/1419463/ (TV shows use movie links), or bare ids.

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

Subject search (title, person) or, in group search, the keyword a discussion title must contain. Chinese or English.

## `searchType` (type: `string`):

Also sets the type of bare ids in Subject URLs (movie by default).

## `topicUrls` (type: `array`):

Links like https://www.douban.com/group/topic/502497554/ for the group topic mode.

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

Per chart, per search query, per group search; in comment and review modes, per subject (Douban shows logged-out visitors up to 150 short comments and 40 reviews per subject, most helpful first).

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

Open each subject for languages, all release dates, durations, intro, tags, star distribution and want/watched counts. Chart rows already have rating, year, countries, genres, directors and actors.

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

Add the most helpful short comments (短评) of every subject, with stars and helpful votes.

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

Up to 150 (what Douban shows logged out).

## `includeReviews` (type: `boolean`):

Add the most helpful long reviews (影评) of every subject, with stars, helpful and unhelpful votes.

## `maxReviews` (type: `integer`):

Up to 40 (what Douban shows logged out).

## `fetchFullReviewBody` (type: `boolean`):

Fetch each review's full text (one extra request each, same price). Off: title and abstract only.

## `fetchTopicContent` (type: `boolean`):

Also read each found discussion's text and replies.

## `maxRepliesPerTopic` (type: `integer`):

Replies attached to each topic row.

## `sentimentAnalysis` (type: `boolean`):

Lexicon-based sentiment (positive, negative, neutral, score -1 to +1) on comments, reviews and topics.

## `deltaMode` (type: `boolean`):

For scheduled runs: return only comments, reviews and topics no earlier run with the same state key delivered.

## `deltaStateKey` (type: `string`):

Name of an independent tracking stream for delta mode.

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

Usually not needed. Without a proxy, the Actor switches to Apify Proxy by itself if Douban blocks a request.

## Actor input object example

```json
{
  "mode": "charts",
  "charts": [
    "movie_top250"
  ],
  "sortBy": "default",
  "subjectUrls": [
    "https://movie.douban.com/subject/1291546/"
  ],
  "searchType": "all",
  "maxResults": 50,
  "includeDetails": false,
  "includeComments": false,
  "maxComments": 20,
  "includeReviews": false,
  "maxReviews": 10,
  "fetchFullReviewBody": true,
  "fetchTopicContent": false,
  "maxRepliesPerTopic": 50,
  "sentimentAnalysis": false,
  "deltaMode": false,
  "deltaStateKey": "default",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `overview` (type: `string`):

Movies, TV, books and music with ratings.

## `comments` (type: `string`):

Short comments with stars and helpful votes.

## `reviews` (type: `string`):

Long reviews with full text.

## `topics` (type: `string`):

Group discussions.

## `all` (type: `string`):

Every field of every item.

# 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 = {
    "charts": [
        "movie_top250"
    ],
    "subjectUrls": [
        "https://movie.douban.com/subject/1291546/"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("improved_knot_vyk/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 = {
    "charts": ["movie_top250"],
    "subjectUrls": ["https://movie.douban.com/subject/1291546/"],
}

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

```

## MCP server setup

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