# Douyin Hot Search - Trending Topics, Rank & Heat (`xtracto/douyin-hot-search`) Actor

Snapshot Douyin's hot-search chart: every trending topic with its rank, heat value, video count and timestamp, plus the real-time rising board. Schedule it to build a trend history of what China is watching. HTTP-only, no account, no signature.

- **URL**: https://apify.com/xtracto/douyin-hot-search.md
- **Developed by:** [Farhan Febrian Nauval](https://apify.com/xtracto) (community)
- **Categories:** Social media
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.34 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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

## Douyin Hot Search — Trending Topics, Rank & Heat

Snapshot Douyin's hot-search chart: every trending topic with its rank, heat value, video count
and timestamp, plus the smaller **实时上升热点** (real-time rising) board. Schedule it to build a
trend history of what China is watching.

HTTP-only, no account, **no signature**.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `boards` | array | `["hot"]` | `hot` (main chart, ~50 topics), `rising` (~5). Both come from one request |
| `maxRounds` | integer | `3` | Retries on a zero-byte response |
| `proxyConfiguration` | object | Apify proxy | Optional — a bare IP answered in testing |

### Output

```jsonc
{
  "_source": "S1-hot-search-api",
  "_scrapedAt": "2026-09-09T04:46:23Z",
  "board": "hot-search",

  "rank": 1,
  "word": "送你一口秋天味道",
  "hotValue": 11687559,
  "videoCount": 3,
  "discussVideoCount": 1,
  "isPromoted": false,
  "groupId": "7681506653736572198",
  "wordType": 1,
  "eventTime": 1788841307,
  "eventTimeIso": "2026-09-09T04:21:47Z",
  "coverUrl": "https://…",
  "boardActiveTime": "2026-09-09 04:44:11"
}
```

### Two things this actor gets right that a naive one does not

**The chart contains a pinned entry that reuses rank 1.** Douyin puts an editorial/promoted slot
at `position: 1` alongside the genuine number one, so the raw board has **two rank-1 rows** — and
the promoted one has `hot_value: 0` and no `group_id`. Sorting by rank or heat without noticing
gives you a bogus number one with zero heat. Every row carries `isPromoted`, so you can filter it
or study it; after flagging, the 50 organic rows have 50 distinct ranks.

**A zero-byte 200 is a failure, not an empty board.** Douyin answers an unrecognised client with
`200` and no body. The actor retries that rather than reporting "no trending topics today".

### What is *not* covered, and why

Only the hot-search board is reachable anonymously. Probed and re-verified:

| Endpoint | Result |
|---|---|
| `/hot/search/list/` | ✅ `status_code: 0`, real data |
| `/general/search/single/` | ❌ `status_code 2483` — 请先登录 (**login required**) |
| `/aweme/post/`, `/user/profile/other/`, `/comment/list/` | ❌ **200 with a zero-byte body** — needs an `a_bogus` signature |
| `www.douyin.com/user/…`, `/video/…` | ❌ identical 72.9 KB client-rendered shell |

So this is a hot-search actor and is named as one. Douyin search and profile scraping would need
a signing sidecar; that is out of scope here.

`board_type` is accepted by the endpoint and **ignored** — `0`, `2` and `3` return the identical
49 words — so it is not offered as an input.

### Known limits

| Limit | Detail |
|---|---|
| One snapshot per run | The board is a live chart; history comes from scheduling the actor, not from paging |
| Chinese text | Topics are returned as published, untranslated |
| `hotValue` is Douyin's own scale | Comparable across topics in one snapshot, not an absolute view count |

# Actor input Schema

## `boards` (type: `array`):

hot = Douyin's main hot-search chart (about 49 topics). rising = the smaller 实时上升热点 real-time rising board (about 5). Both come from one request, so picking both costs nothing extra.

## `maxRounds` (type: `integer`):

Douyin answers an unrecognised client with a zero-byte 200; the actor treats that as a retryable failure rather than an empty board.

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

Optional. The board answered a bare IP in testing.

## Actor input object example

```json
{
  "boards": [
    "hot"
  ],
  "maxRounds": 3,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

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

One row per scraped record, stored in the run's default dataset.

# 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("xtracto/douyin-hot-search").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("xtracto/douyin-hot-search").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 '{}' |
apify call xtracto/douyin-hot-search --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,xtracto/douyin-hot-search"
        }
    }
}
```

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/eRyyUamm6YG43u9R2/builds/yHyYEe8LTP6Xcc3cZ/openapi.json