# Douyin Hot Search Scraper (`khadinakbar/douyin-hot-search-scraper`) Actor

Scrape Douyin (抖音) live hot-search boards: rank, hot value, video counts, cover, event time. Boards: hotspot, seeding, entertainment, social, challenge. Not for keyword video search or TikTok trends. $0.005/topic.

- **URL**: https://apify.com/khadinakbar/douyin-hot-search-scraper.md
- **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community)
- **Categories:** Social media, News, MCP servers
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 hot topic scrapeds

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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

## Douyin Hot Search Scraper

Turn Douyin (抖音) live 热榜 boards into **one dataset row per unique trending topic** — rank, hot value, video count, cover image, and event time. Built for China-market researchers, brand monitors, and AI agents that need a structured hot-search pulse without a Douyin login.

### Best fit for this Actor

- Start with the `hotspot` board when you need Douyin's main public 热点榜 pulse.
- Pair this Actor with keyword video search when a topic spike needs the videos behind it.
- Continue with creator profile enrichment when a trend points to a specific account.

### Practical scenario

A social-listening analyst schedules a morning run with `boards = ["hotspot", "social"]` and `maxResultsPerBoard = 30`. The dataset returns unique topics with rank, 热度 (`hotValue`), video count, cover URL, and `eventTime`. Topics that appear on both boards are saved once and billed once. The analyst exports CSV into a daily trend sheet, then passes a `word` into Douyin search for the videos behind a spike.

### Quick start input

```json
{
  "boards": ["hotspot"],
  "maxResultsPerBoard": 20
}
```

`boards` selects which public Douyin hot-search lists to request. `maxResultsPerBoard` caps each board (1–60). Prefill `20` keeps quality tests cheap.

#### Multi-board example

```json
{
  "boards": ["hotspot", "seeding", "entertainment", "social", "challenge"],
  "maxResultsPerBoard": 50
}
```

### Input reference

| Field | Type | What it controls |
| --- | --- | --- |
| `boards` | string\[] | Boards to request: `hotspot`, `seeding`, `entertainment`, `social`, `challenge`. Default `["hotspot"]`. |
| `maxResultsPerBoard` | integer | Cap per board (1–60). Prefill `20` for cheap quality tests. |
| `proxyConfiguration` | object | Optional Apify proxy. Direct HTTP is the default path. |

### What data you receive

One dataset item is one unique trending topic (cross-board `sentenceId` dedupe).

```json
{
  "type": "trending",
  "board": "hotspot",
  "rank": 1,
  "word": "今天是教师节",
  "hotValue": 12157519,
  "videoCount": 15,
  "viewCount": null,
  "coverImageUrl": "https://p26-sign.douyinpic.com/example~noop.jpeg",
  "eventTime": "2026-09-10T05:11:26.000Z",
  "boardActiveTime": "2026-09-10 21:12:04",
  "sentenceId": "2642852",
  "provider": "douyin-web",
  "scrapedAt": "2026-09-10T12:00:00.000Z"
}
```

| Field | Meaning |
| --- | --- |
| `board` / `rank` / `word` | Board that first returned the topic, 1-based rank, topic text |
| `hotValue` / `videoCount` / `viewCount` | Public 热度 and related counts when Douyin exposes them |
| `coverImageUrl` / `eventTime` / `boardActiveTime` | Cover URL and board timing fields |
| `sentenceId` / `provider` / `scrapedAt` | Dedupe id, source label, and collection time (provenance) |

`OUTPUT` and `RUN_SUMMARY` in the default key-value store hold `outcome`, `itemsPushed`, and `chargedEventCounts`.

### Use through the API

```bash
curl -X POST "https://api.apify.com/v2/acts/khadinakbar~douyin-hot-search-scraper/runs" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"boards":["hotspot"],"maxResultsPerBoard":20}'
```

Download rows as JSON, CSV, Excel, or HTML from the Dataset tab. The Store slug is `khadinakbar/douyin-hot-search-scraper`.

### Use with AI agents through Apify MCP

> Fetch Douyin hotspot board topics with maxResultsPerBoard 20. Return rank, word, hotValue, videoCount, coverImageUrl, eventTime, and scrapedAt. Read OUTPUT.outcome and the dataset for readback; keep source provenance on provider and sentenceId. Cost signal: about $0.005 per unique hot-topic plus platform usage. Keep scope to public hot-search boards; for keyword videos or creator profiles, continue with the sibling Actors.

Connect via <https://mcp.apify.com>. Inspect the terminal outcome before treating an empty dataset as an outage — empty challenge boards often finish as a valid empty board outcome.

### Connect the workflow

- After you have a trending `word`, search Douyin videos with [Douyin Search Scraper](https://apify.com/khadinakbar/douyin-search-scraper).
- When a trend points to a creator, enrich the account with [Douyin Profile Scraper](https://apify.com/khadinakbar/douyin-profile-scraper).
- For global TikTok hashtag trends instead of Douyin 热榜, start with [TikTok Trending Hashtags Scraper](https://apify.com/khadinakbar/tiktok-trending-hashtags-scraper).

### Pricing

This Actor uses Pay per event plus Apify platform usage. The live Pricing tab is the current source of truth for billing details.

- `apify-actor-start`: $0.00005 per run
- `hot-topic`: $0.005 per unique trending topic

A 20-topic hotspot sample is about $0.10 in result events plus platform usage. Cross-board duplicates are billed once.

### How it works

1. Warm a short HTTP session against douyin.com.
2. Request Douyin's public hot-search list for each selected board (`board_type` / `board_sub_type`).
3. Prefer the web list endpoint, then fall back to the public snssdk list route when needed.
4. Validate topics, dedupe by `sentenceId`, charge `hot-topic`, then write the dataset row.

### Best results

- Start with `hotspot` only to confirm the data shape before adding secondary boards.
- Cap `maxResultsPerBoard` when you only need the top of the board.
- Schedule runs for a steady pulse rather than high-concurrency bursts.
- Treat signed cover URLs as short-lived; download soon if you need durable assets.
- When your region needs a China-reachable path, enable Apify Residential in `proxyConfiguration`.

### Builder's note

I found that Douyin's public hot-search list still returns live 热点榜 JSON over unsigned HTTP after a short douyin.com warmup, even when keyword search is CAPTCHA-walled from non-CN residential pools. In my testing, unsigned secondary board selectors can collapse onto overlapping lists, and the challenge board is often empty — so this Actor stays HTTP-only with snssdk as a bounded fallback, dedupes by `sentenceId` before charging, and records honest board-level empty outcomes instead of fabricating topics.

### Responsible use

Use this Actor on publicly available Douyin hot-search rankings you are authorized to process, follow applicable laws and Douyin's terms of service, and keep outputs inside your own compliance workflow.

Douyin is a trademark of its owner. This independent Actor is not affiliated with, associated with, or endorsed by Douyin or ByteDance.

Issues and feature requests: use the Actor Issues tab on Apify.

# Actor input Schema

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

Which Douyin hot-search boards to request. Each board returns up to ~50 live topics when Douyin exposes that list. Hotspot is the main real-time 热点榜. Seeding is 种草榜 (product/recommendation). Entertainment is 娱乐榜. Social is 社会榜. Challenge is 挑战榜. Default and prefill is hotspot only for a cheap quality sample.

## `maxResultsPerBoard` (type: `integer`):

Maximum trending topics to keep per selected board after parse. Douyin typically publishes ~50. Prefill 20 keeps quality tests cheap. Range 1–60.

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

Optional Apify proxy. Leave off for the default direct HTTP path used by most runs. Enable Residential only if Douyin blocks your egress region.

## Actor input object example

```json
{
  "boards": [
    "hotspot"
  ],
  "maxResultsPerBoard": 20
}
```

# Actor output Schema

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

One row per unique Douyin hot-search topic.

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

Final outcome, itemsPushed, topicsFound, and chargedEventCounts.

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

Per-board outcomes, retries, and billing counters.

# 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 = {
    "boards": [
        "hotspot"
    ],
    "maxResultsPerBoard": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("khadinakbar/douyin-hot-search-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 = {
    "boards": ["hotspot"],
    "maxResultsPerBoard": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("khadinakbar/douyin-hot-search-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 '{
  "boards": [
    "hotspot"
  ],
  "maxResultsPerBoard": 20
}' |
apify call khadinakbar/douyin-hot-search-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,khadinakbar/douyin-hot-search-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/Avp9fVbe8WiptQDj5/builds/W6srtzODucm7iABVj/openapi.json