# Douban API — China Movie & TV Ratings, Top 250 & Hot Lists (`nexgendata/douban-tracker`) Actor

Track Douban (豆瓣), China's IMDb/Goodreads. Pull hot lists, Top 250, now-playing, top-rated & keyword search for movies & TV — title, rating, cover image, Douban URL, rank. China's canonical consumer-taste & IP-reception source for brand & consumer research. No login; optional Notion delivery.

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

## Pricing

from $50.00 / 1,000 rated items

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/platform/actors/running/actors-in-store#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 API — China Movie & TV Ratings, Top 250 & Hot Lists (豆瓣)

Track Douban (豆瓣) — China's IMDb-meets-Goodreads, where Chinese audiences rate and review films, TV and books and where a movie's 豆瓣 score makes or breaks its word-of-mouth. Pull hot lists, the Top 250 chart, now-playing and top-rated charts (or keyword-search any title) with ratings, rank, cover art and Douban URLs in clean JSON. It's the canonical source for Chinese consumer taste and IP reception — and you can optionally deliver each run straight to a Notion page.

**Optional delivery:** Send results to your own Notion database or Supabase table in the same run, via Apify's native [MCP connectors](https://docs.apify.com/platform/integrations/mcp-connectors) — the Actor never sees your credentials. One-click connect: [Notion](https://console.apify.com/account/integrations/mcp-connectors/new?serverUrl=https%3A%2F%2Fmcp.notion.com%2Fmcp) or [Supabase](https://console.apify.com/account/integrations/mcp-connectors/new?serverUrl=https%3A%2F%2Fmcp.supabase.com%2Fmcp). Leave blank to get the dataset as usual.

No login, no Chinese phone number, no Douban API key — list in, clean ranked rows out.

### 📊 Sample Output

[![Douban API sample output — China movie hot list with title, Douban rating, Douban ID, and subject URL for consumer-taste and IP-reception research](https://api.apify.com/v2/key-value-stores/8gLgXMBveEI1tTz1z/records/douban-tracker-sample)](https://apify.com/nexgendata/douban-tracker)

Real titles returned by this actor for **`category: movie`, `listType: hot`** — every row below comes straight from a live run on the Chinese-language Douban hot list:

| # | Title (电影) | Rating | Douban ID | Subject URL |
|---|---|---|---|---|
| 1 | 大濛 | 8.0 | 36680492 | movie.douban.com/subject/36680492/ |
| 2 | 木挽町复仇记 | 7.2 | 37516907 | movie.douban.com/subject/37516907/ |
| 3 | 单程夜航 | 6.8 | 38407729 | movie.douban.com/subject/38407729/ |
| 4 | 我的妈耶 | 6.6 | 36217763 | movie.douban.com/subject/36217763/ |
| 5 | 世界的主人 | 9.1 | 37116612 | movie.douban.com/subject/37116612/ |

> Each title also carries a high-resolution `cover_image` poster URL and the original Chinese title — handy for building content catalogs, recommendation datasets, or IP-licensing trackers.

### What you get

Per title, you get a flat, typed record:

- **Identity** — `title` (Chinese), `original_title`, `douban_id`, `douban_url` (direct subject page)
- **Score** — `rating` (Douban's 10-point score), `rating_count` *where Douban exposes it*
- **Ranking** — `rank` (position in the requested list), `list_type`, `category`
- **Metadata** — `year`, `genres[]`, `director`, `author`, `artist` *(populated where the endpoint returns them)*
- **Media** — `cover_image` (high-res poster URL)
- **Reference** — `summary`, `data_source`, `scraped_at`

> Note: Douban's open list endpoints expose the score but **not** vote counts — `rating_count` is `null` for list pulls. Richer metadata (`year`, `genres`) is populated on Top 250 / detail-backed lists and keyword `query` lookups. We never fabricate fields the source doesn't return.

### Sample input

```json
{
  "category": "movie",
  "listType": "top250",
  "maxItems": 20,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}
```

More examples:

```json
{ "category": "movie", "listType": "hot", "maxItems": 12 }
```

```json
{ "category": "tv", "listType": "now-playing", "maxItems": 40 }
```

```json
{ "category": "movie", "query": "流浪地球", "maxItems": 20 }
```

### 📊 Sample Output (JSON)

```json
{
  "title": "肖申克的救赎",
  "original_title": "肖申克的救赎",
  "rating": 9.7,
  "rating_count": null,
  "rank": 1,
  "douban_url": "https://movie.douban.com/subject/1292052/",
  "cover_image": "https://img3.doubanio.com/view/photo/s_ratio_poster/public/p480747492.jpg",
  "author": null,
  "summary": "1994 / 美国 / 犯罪 剧情"
}
```

### Input

| Input | Type | Description |
|---|---|---|
| `category` | enum | `movie`, `tv` (full list support) or `book`, `music` (keyword `query` only). |
| `listType` | enum | `hot`, `top250`, `now-playing`, `new`, `top-rated` (movie/TV; ignored when `query` is set). |
| `query` | string | Optional keyword lookup; overrides `listType`, works across categories. |
| `maxItems` | integer | Hard cap on returned items (1–200). |
| `proxyConfiguration` | proxy | RESIDENTIAL strongly recommended (Douban is rate-sensitive). |
| `notionConnector` / `supabaseConnector` | mcpConnector | Optional delivery to your own Notion page or Supabase table. |

### How it works

Douban is one of the most anti-bot-defended sites in the Chinese web. This actor routes through Apify residential proxy and reads movie/TV lists from Douban's own open `search_subjects` rated-list endpoint rather than scraping defended HTML. The `maxItems` cap (1–200) is a hard ceiling. Book and music are supported via keyword `query` only.

### 💰 Pricing example

Pay-Per-Event — you only pay for what lands in your dataset:

- **Actor start:** $0.005
- **Per item:** $0.05

A 100-title pull = **$5.01**; a 12-title hot-list check = **$0.605**. No monthly minimum, no seats.

### Use cases

- **Brand / IP** — gauge Chinese reception of a film, show or franchise before localizing or licensing.
- **Consumer research** — track Chinese taste and which genres resonate.
- **Social listening** — use Douban ratings as a word-of-mouth signal for entertainment IP.
- **China-watching** — build a ratings time-series for the now-playing and hot charts.

### ❓ FAQ

**Is the official Douban API still available?** The legacy `api.douban.com/v2` is effectively closed; this actor reads open list endpoints with no key.

**Can I scrape the Douban Top 250?** Yes — `listType: "top250"` (movies or TV). Hot, now-playing, new and top-rated are also supported.

**Does it return vote counts?** List endpoints expose the score but not vote counts (`rating_count` is `null`).

**Can I search for a specific title?** Yes — `query` overrides the list and works across movie/TV/book/music.

**Does it require login?** No, but Douban is rate-sensitive — a residential proxy is strongly recommended.

### 🔗 Related actors — China social

- [Weibo Hot Search Tracker](https://apify.com/nexgendata/weibo-hot-search-tracker) — the live Weibo 热搜 leaderboard as structured data
- [Bilibili Video Search](https://apify.com/nexgendata/bilibili-video-search) — search and rank Bilibili videos
- [China Trends Tracker](https://apify.com/nexgendata/china-trends-tracker) — trending across China's biggest platforms in one feed
- [RedNote (Xiaohongshu) Scraper](https://apify.com/nexgendata/rednote-scraper) — China's lifestyle/discovery platform
- [Zhihu Q\&A Tracker](https://apify.com/nexgendata/zhihu-qa-tracker) — China's Quora — high-intent discussion and opinion

***

**Get free Apify credits & save 30% on platform fees:** <https://apify.com/nexgendata>

# Actor input Schema

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

What to track. movie/tv use Douban's open rated-list endpoint (fully supported). book/music only support keyword `query` search (their list pages are anti-bot defended).

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

Which Douban list to pull (movie/tv only). Ignored when `query` is set.

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

Optional keyword search via Douban's open suggest endpoint. When set, overrides listType. Works across categories for title lookups.

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

Hard cap on returned items (1-200).

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

Residential proxy is strongly recommended for Douban (rate-sensitive, anti-bot). Defaults to Apify RESIDENTIAL.

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

Optional. Connect your Notion workspace and the results are also written as a Notion page in the same run — the Actor never sees your Notion credentials. Authorize a Notion MCP connector in Apify Console → Settings → API & Integrations, then select it here.

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

Optional. The Notion page ID to create the page under. If blank, Notion creates a private page in your workspace.

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

Optional. Connect your own Supabase project and the results are also inserted into a table in the same run — the Actor never sees your Supabase credentials. Authorize a write-scoped, project-scoped Supabase MCP connector in Apify Console (Settings -> Integrations), then select it here.

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

Target table in the public schema (created if missing, with id, a jsonb data column, and a scraped\_at timestamp). Default: nexgendata\_leads.

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

Your Supabase project reference (e.g. abcdefghijklmnop). Required unless your connector URL is already project-scoped. Find it in your project URL: supabase.com/dashboard/project/THIS\_PART.

## `deliveryDedup` (type: `boolean`):

When on (default), records already delivered in a previous run are not delivered again to the same destination — so scheduled runs only push new items. Turn off to deliver every record on every run.

## Actor input object example

```json
{
  "category": "movie",
  "listType": "hot",
  "maxItems": 20,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  },
  "supabaseTable": "nexgendata_leads",
  "deliveryDedup": true
}
```

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("nexgendata/douban-tracker").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("nexgendata/douban-tracker").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call nexgendata/douban-tracker --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=nexgendata/douban-tracker",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/xHFigifkTRFoGhKVO/builds/UiyXBIJxbWcx7Aijl/openapi.json