# Douban Scraper - Movies, TV & Ratings (豆瓣) (`apricot_blackberry/douban-scraper`) Actor

Douban (豆瓣) is the rating Chinese audiences actually trust — and this pulls it clean. Browse movie/TV charts, search titles, and get ratings with cast and directors, cookie-free and no login. Built for China entertainment and localization research.

- **URL**: https://apify.com/apricot\_blackberry/douban-scraper.md
- **Developed by:** [Creator Fusion](https://apify.com/apricot_blackberry) (community)
- **Categories:** Social media, AI, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $6.00 / 1,000 subject details

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?

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 — Movies, TV & Ratings (豆瓣)

**Cookie-free Douban / 豆瓣 scraper.** Douban is China's IMDb + Goodreads — the authoritative source for Chinese-audience ratings and taste. Three modes:

1. **Browse charts** — pull movie or TV lists by tag (热门 / 最新 / 经典 / 豆瓣高分 / 华语 / 日本 …). No input, no login.
2. **Search** — find titles by keyword (title, year, type, poster).
3. **Subject details** — Douban rating, cast, directors, and more by subject id or URL.

Perfect for China entertainment research, localization/content decisions, and taste-graph analysis. No account, no cookie, no CAPTCHA. Typed JSON, one dataset per run.

### Quick start

Hot movies (just press Start):

```json
{}
```

Browse top-rated TV, or search:

```json
{ "type": "tv", "tag": "豆瓣高分" }
```

```json
{ "keywords": ["流浪地球"] }
```

### Output (by rowType)

- **subject** (browse): `subjectId`, `type`, `title`, `rating`, `cover`, `url`.
- **search-result**: `subjectId`, `title`, `subTitle`, `year`, `type`, `cover`, `url`.
- **subject-detail**: `subjectId`, `title`, `rating`, `types`, `releaseYear`, `actors`, `directors`, `cover`, `url`.

### Why this one

- **Cookie-free** — pure public-endpoint extraction, no login token.
- **Douban ratings** — the rating Chinese audiences actually trust, in structured form.
- **Agent-ready** — `rowType` discriminator on every row + a SUMMARY in the key-value store.
- **Self-healing** — direct first (free); on rate-limit/failure it retries through Apify residential proxy with a fresh rotating session before giving up, so proxy is billed only when needed.

***

### 中文说明（豆瓣数据采集）

**无需登录 Cookie 的豆瓣采集工具：**

1. **榜单浏览** — 按标签拉取电影/电视剧列表（热门、最新、经典、豆瓣高分、华语、日本等），无需任何输入。
2. **搜索** — 按关键词搜标题（片名、年份、类型、海报）。
3. **条目详情** — 按条目 id 或链接获取豆瓣评分、演职员等信息。

适合国内影视内容研究、本地化选片、口碑分析。

```json
{ "type": "tv", "tag": "豆瓣高分" }
```

Apify 平台在中国大陆及台湾地区可正常访问，每月 $5 免费额度，无需信用卡即可试用。

***

### For AI agents

```bash
curl -X POST "https://api.apify.com/v2/acts/apricot_blackberry~douban-scraper/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" -d '{}'
```

Empty input returns hot movies (never an error). Filter on `rowType` (`subject` / `search-result` / `subject-detail`).

### Honest limits

- Full long-form **reviews** and **comment threads** live behind Douban's anti-scraping wall and are not in this cookie-free version (ratings, charts, search, and subject details are).
- Books/music use different subject domains; this version focuses on movies and TV.

# Actor input Schema

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

Auto-detected: subject ids/URLs -> details; keywords -> search; nothing -> browse charts.

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

Content type for browse mode.

## `tag` (type: `string`):

Douban tag to browse (e.g. 热门, 最新, 经典, 豆瓣高分, 华语, 日本).

## `keywords` (type: `array`):

Movie/TV titles to search for.

## `subjectIds` (type: `array`):

Douban subject ids or URLs, e.g. https://movie.douban.com/subject/1292052/

## `maxItems` (type: `integer`):

Cap on rows per run.

## `delayBetweenRequests` (type: `integer`):

Pause between API calls.

## `navigationTimeoutMs` (type: `integer`):

Per-request timeout in milliseconds.

## `maxProxyRetries` (type: `integer`):

If a direct request fails or is rate-limited, retry through Apify residential proxy with a fresh rotating session, up to this many times, before giving up. 0 disables proxy fallback.

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

Self-healing: DIRECT first (free), then Apify residential proxy with a fresh rotating session only if a request fails — so you pay for proxy only when needed. Set your own proxy to override. Proxy data is billed to your Apify account.

## Actor input object example

```json
{
  "type": "movie",
  "tag": "热门",
  "keywords": [],
  "subjectIds": [],
  "maxItems": 50,
  "delayBetweenRequests": 700,
  "navigationTimeoutMs": 25000,
  "maxProxyRetries": 3
}
```

# 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 = {
    "keywords": [],
    "subjectIds": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("apricot_blackberry/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 = {
    "keywords": [],
    "subjectIds": [],
}

# Run the Actor and wait for it to finish
run = client.actor("apricot_blackberry/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 '{
  "keywords": [],
  "subjectIds": []
}' |
apify call apricot_blackberry/douban-scraper --silent --output-dataset

```

## MCP server setup

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