# Douban Scraper — Chinese Movie & TV Ratings (`logiover/douban-movie-scraper`) Actor

Scrape Douban, China's largest film and television review community. Extract title, Douban rating, subject ID and link, poster image, episode information and whether a title is new or streamable, across popular, newest, top-rated and hidden-gem listings.

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

## Pricing

from $2.10 / 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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Douban Scraper — Chinese Movie & TV Ratings

China's largest film and television community in rows: title, Douban rating, subject ID and link, poster, episode progress and whether a title is new or streamable — films and TV series.

### What does the Douban Scraper do?

This Actor collects titles from **Douban**, the review community at the centre of Chinese film and television culture. It returns one row per film or series with the **Douban rating** — the number Chinese audiences actually cite, and one that regularly disagrees with Western aggregators on the same title.

Getting a large set out takes some care. The listing endpoint answers one tag at a time and stops handing out rows a few hundred deep, so asking it for "everything" quietly returns the same opening block over and over. This Actor cuts the crawl into **one query per tag** and walks the tags in turn, which is what reaches past that ceiling.

### Who is it for?

- **Film and TV distributors** assessing how a title landed with Chinese audiences.
- **Streaming and licensing teams** building a catalogue view of the Chinese market.
- **Market researchers** comparing Chinese reception against Western ratings.
- **Media analysts and journalists** covering Chinese entertainment.
- **Academics** studying cross-cultural differences in audience reception.
- **Recommendation and catalogue platforms** seeding Chinese-language title data.

### Use cases

- Build a rated catalogue of Chinese films and series.
- Compare a title's Douban score against IMDb or Letterboxd for the same film.
- Track newly released titles and their ratings as they settle.
- Find highly rated but little-known titles through the hidden-gems tag.
- Separate domestic from imported titles using the language tags.
- Watch which currently-airing series are streamable and how far along they are.
- Feed an AI agent Chinese ratings data for entertainment questions.

### Why use this Douban Scraper?

- **Tag-partitioned crawling** that reaches past the listing endpoint's paging ceiling.
- **Ratings kept honest** — an unrated title reports as empty rather than as a score of zero. See the FAQ.
- **Films and TV series** from one Actor.
- **Any tag you like**, or the eight main ones by default.
- **Direct links** to each title's Douban page.
- **Keyless, login-free and proxy-free.**

### What data can you extract?

One row per title. Anything the source left blank comes back as `null`.

| Field | Description |
| --- | --- |
| `subjectId` | Douban subject ID |
| `url` | Link to the Douban page |
| `title` | Title, in Chinese |
| `rating` | Douban rating out of 10 |
| `mediaType` | Movie or TV |
| `tag` | The tag this row was found under |
| `episodeInfo` | Episode progress, for airing series |
| `isNew` | Whether Douban marks it as new |
| `isPlayable` | Whether it is streamable on Douban |
| `posterUrl` | Poster image |
| `scrapedAt` | ISO timestamp of collection |

#### Sample output

```json
{
  "subjectId": "36810153",
  "url": "https://movie.douban.com/subject/36810153/",
  "title": "花开锦绣",
  "rating": null,
  "mediaType": "TV",
  "tag": "热门",
  "episodeInfo": "更新至29集",
  "isNew": "No",
  "isPlayable": "Yes",
  "posterUrl": "https://img3.doubanio.com/view/photo/s_ratio_poster/public/p2934718593.jpg",
  "scrapedAt": "2026-08-23T11:37:29.949Z"
}
```

### How to use the Douban Scraper

#### Option A — the main tags

Leave **Tags** empty and the crawl walks the eight main ones: 热门 (popular), 最新 (newest), 豆瓣高分 (top rated), 冷门佳片 (hidden gems), 华语, 欧美, 韩国 and 日本.

#### Option B — specific tags

Put your own comma-separated tags in Chinese, exactly as Douban writes them — for example `豆瓣高分,冷门佳片`.

#### Option C — TV series

Set **Media type** to *TV series*. Tags differ slightly for television, so try 热门 and 国产剧.

### Input parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `mediaType` | select | `movie` | Films or TV series |
| `tags` | string | *(empty)* | Comma-separated Chinese tags; empty walks the eight main ones |
| `maxResults` | integer | 1000 | Stop after this many titles (max 20,000) |
| `proxyConfiguration` | object | *(off)* | Optional; the endpoint answers without one |

### Tips for best results

- **More tags means more titles.** Each tag yields a few hundred rows before the endpoint stops advancing, so the way to a large export is breadth of tags, not a bigger maximum.
- **Treat an empty `rating` as unrated**, not as zero. Douban withholds a score until a title has enough votes, which is why new releases arrive blank.
- **`subjectId` is the join key** to any other Douban data and is stable; the title is not, since Chinese releases are often renamed.
- **`tag` is kept on every row** so a combined multi-tag export stays segmented — the same title can legitimately appear under two tags.
- **`episodeInfo` only exists for airing series**, so expect it on a small share of TV rows and none of the film rows.

### Integrations

Connect the dataset to Make, Zapier, Airbyte, Google Sheets, Slack, GitHub or any HTTP endpoint through Apify integrations, or schedule a run and push results into a warehouse with a webhook.

### API usage

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_API_TOKEN>")
run = client.actor("logiover/douban-movie-scraper").call(run_input={
    "mediaType": "movie",
    "tags": "豆瓣高分,冷门佳片",
    "maxResults": 1000,
})
rows = list(client.dataset(run["defaultDatasetId"]).iterate_items())
rated = [r for r in rows if r["rating"]]
top = sorted(rated, key=lambda r: r["rating"], reverse=True)[:5]
for r in top:
    print(r["rating"], r["title"], r["url"])
```

### Use with AI agents (MCP)

The Actor is callable from the Apify MCP server, so an assistant can pull Chinese film and TV ratings directly and answer questions about reception in that market.

### FAQ

#### Do I need a Douban account or API key?

No. This Actor reads Douban's public listing endpoint; there is nothing to register.

#### How many titles can one run return?

Up to 20,000. Because each tag stops yielding after a few hundred rows, the practical total depends on how many tags you crawl — the default eight comfortably return several hundred.

#### Why crawl tag by tag instead of just paging?

Because paging alone does not work. The endpoint keeps answering but stops advancing past a few hundred rows and re-serves the opening block, so a naive page loop collects duplicates and looks like it succeeded. Splitting by tag keeps each query inside the window it will actually page through.

#### Why is the rating sometimes empty?

Because Douban has not published one yet. It withholds a score until a title gathers enough votes, and reports `0` in the meantime — which is "unrated", not a score of zero, so it is stored as empty rather than as a misleading number.

#### Are titles in Chinese?

Yes. Douban is a Chinese-language site and titles come back exactly as published, in Simplified Chinese. Foreign films appear under their Chinese release names.

#### What tags can I use?

Any that Douban itself uses, written in Chinese — 热门, 最新, 豆瓣高分, 冷门佳片, 华语, 欧美, 韩国, 日本 for films, and 国产剧, 美剧, 日剧, 韩剧 among others for television.

#### Does it collect reviews or cast?

No. This Actor collects the listing record: title, rating, type and links. Reviews and full credits live on each title's own page, and every row carries a `url` to it.

#### Can I export to CSV or Excel?

Yes — every run's dataset exports to JSON, CSV, Excel, XML or JSONL.

#### How fresh is the data?

Each run reads the listing live, so ratings are as current as Douban's own at the moment you run it.

#### Why did my run return zero titles?

Usually a tag that Douban does not recognise. Tags are Chinese words and must match exactly; start with the defaults and adjust from there.

### Is it legal to scrape Douban?

This Actor reads Douban's public listing endpoint — no accounts, no logins, no private content and no user reviews. Titles, aggregate ratings and poster links are catalogue information published for public view. Aggregate ratings are not personal data, but you remain responsible for how you use the results and for respecting the platform's terms in your own jurisdiction.

### Related scrapers

- **Letterboxd Film Review Scraper** — Western film ratings and reviews.
- **IMDb Scraper** — titles, ratings and credits.
- **MyAnimeList Scraper** — anime and manga ratings.
- **Bilibili Scraper** — trending videos from China's video community.

# Actor input Schema

## `mediaType` (type: `string`):

Films or television series.

## `tags` (type: `string`):

Douban tags, comma separated, written in Chinese exactly as the site does — e.g. 热门 (popular), 最新 (newest), 豆瓣高分 (top rated), 冷门佳片 (hidden gems), 华语, 欧美, 韩国, 日本. Leave empty to walk the eight main tags.

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

Stop after this many titles. Each tag yields a few hundred, so the crawl walks several tags to reach a large total.

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

Douban's listing endpoint answers without a proxy. Enable one if you hit rate limiting on large runs.

## Actor input object example

```json
{
  "mediaType": "movie",
  "tags": "豆瓣高分,冷门佳片",
  "maxResults": 1000,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

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

Every record collected in this run. Open the Dataset tab to browse, filter or export as JSON, CSV or Excel.

# 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 = {
    "mediaType": "movie",
    "maxResults": 1000,
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("logiover/douban-movie-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 = {
    "mediaType": "movie",
    "maxResults": 1000,
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("logiover/douban-movie-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 '{
  "mediaType": "movie",
  "maxResults": 1000,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call logiover/douban-movie-scraper --silent --output-dataset

```

## MCP server setup

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