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

Export current Douyin hot-search topics with ranks, trend metrics, and source links.

- **URL**: https://apify.com/fetch\_cat/douyin-hot-search-scraper.md
- **Developed by:** [Hanna Nosova](https://apify.com/fetch_cat) (community)
- **Categories:** Social media
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.70 / 1,000 trending topics

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

## Douyin Hot Search Scraper

Douyin Hot Search Scraper exports the current public Douyin (抖音) hot-search ranking as structured data for trend monitoring, market research, editorial planning, and Chinese-market analysis. Use this focused **Douyin scraper** and Douyin API workflow to capture a current topic snapshot with ranks, heat, video metrics, badges, timestamps, and public source links.

### Who is it for?

- **Market researchers** comparing fast-moving Douyin conversations.
- **Content and social teams** planning topics around current trends.
- **Analysts and developers** who need a reproducible current-board snapshot in a dataset or API workflow.

### Ready-to-run examples

Use one of these verified public examples to start with a bounded input:

- [Scrape current Douyin hot-search trends](https://apify.com/fetch_cat/douyin-hot-search-scraper/examples/scrape-douyin-hot-search-trends)
- [Use Douyin hot search as an API](https://apify.com/fetch_cat/douyin-hot-search-scraper/examples/douyin-hot-search-api)
- [Export Douyin trend data](https://apify.com/fetch_cat/douyin-hot-search-scraper/examples/export-douyin-trend-data)
- [Monitor Douyin topic ranks and heat](https://apify.com/fetch_cat/douyin-hot-search-scraper/examples/monitor-douyin-topic-ranks)
- [Research current Douyin topics for content planning](https://apify.com/fetch_cat/douyin-hot-search-scraper/examples/research-douyin-topics-for-content)

### What you get

- The ranked **Hot list (抖音热榜)** topics.
- The optional **real-time rising (实时上升热点)** strip as a separate `board` value.
- Topic-level heat, video and discussion metrics, badges, event times, cover images, and public source metadata.

### Use cases

- Capture scheduled snapshots for a trend-monitoring dashboard.
- Compare topic rank and heat between successive runs.
- Find timely research or content-planning themes for the Chinese market.
- Export Douyin data into a warehouse, spreadsheet, or agent workflow.

### Input settings

| Input | Default | Description |
| --- | ---: | --- |
| `maxItems` | `20` | Maximum topics to save (1–100). |
| `includeRisingTopics` | `true` | Include the public real-time rising strip. |

### Output example

```json
{
  "board": "hot",
  "boardName": "Hot list (抖音热榜)",
  "rank": 1,
  "word": "Example trending topic",
  "hotValue": 11394460,
  "videoCount": 15,
  "discussionVideoCount": 1,
  "eventTime": "2026-08-27T00:00:00.000Z",
  "searchUrl": "https://www.douyin.com/search/Example%20trending%20topic"
}
```

### Output fields

| Field | Description |
| --- | --- |
| `board`, `boardName` | Main hot list or real-time rising strip. |
| `rank`, `isPinned`, `peakRank` | Current list position, pin state, and best position. |
| `word`, `sentenceId`, `sentenceTag`, `groupId`, `wordType` | Topic text and public Douyin identifiers/types. |
| `hotValue`, `videoCount`, `discussionVideoCount`, `articleCount`, `liveRoomCount` | Public trend metrics. |
| `label`, `labelName`, `labelImageUrl` | Douyin badge code, readable badge name, and image URL. |
| `eventTime`, `eventTimestamp`, `boardActiveTime`, `trendingDescription` | Snapshot and trend timing/context. |
| `coverUrl`, `coverUrls` | Public topic cover image URLs. |
| `searchUrl`, `hotSpotUrl`, `sourceUrl` | Direct public links and source metadata. |
| `scrapedAt` | ISO timestamp when this Actor captured the row. |

### Working with snapshots

Each run represents the current board at capture time. Schedule repeated runs when you need a timeline, then compare `rank`, `hotValue`, and `eventTime` across exported datasets. Keep `board` in downstream filters so rising topics remain distinct from the ranked hot list.

### Pricing

This Actor charges once when a run starts and once per exported trending topic. Review the current [Apify Pricing tab](https://apify.com/fetch_cat/douyin-hot-search-scraper/pricing) before running for your volume-tier rate.

### Tips and limits

- Poll on a schedule if you need snapshots over time; this Actor returns the current public board, not historical rankings.
- A topic may have missing optional metrics or badge data when Douyin does not provide them.
- The Actor returns the verified public main hot list and its embedded rising strip; it does not offer account-only boards.
- Source ordering and values can change between runs as the public board refreshes.

### API usage

#### Node.js

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('fetch_cat/douyin-hot-search-scraper').call({ maxItems: 20 });
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("fetch_cat/douyin-hot-search-scraper").call(run_input={"maxItems": 20})
items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items)
```

#### cURL

```bash
curl -X POST "https://api.apify.com/v2/acts/fetch_cat~douyin-hot-search-scraper/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"maxItems":20,"includeRisingTopics":true}'
```

### MCP

Add the Actor to an MCP-enabled client:

```bash
claude mcp add apify -- npx -y @apify/mcp-server
```

Example configuration:

```json
{
  "mcpServers": {
    "apify": {
      "command": "npx",
      "args": ["-y", "@apify/mcp-server"],
      "env": { "APIFY_TOKEN": "YOUR_APIFY_TOKEN" }
    }
  }
}
```

Use `https://mcp.apify.com?tools=fetch_cat/douyin-hot-search-scraper` to scope the available tool. **Example prompt:** “Fetch the current Douyin hot-search topics and summarize the top ten by heat.”

### FAQ

**What data can I export with this Douyin scraper?** Current hot-search topics, ranks, heat values, video counts, badges, timestamps, cover images, and public source links.

**Can I run Douyin Hot Search Scraper through an API, schedule, or MCP client?** Yes. Use an API client, schedule repeated snapshots, or add the scoped MCP tool.

**How much does it cost to use Douyin Hot Search Scraper?** It charges once when a run starts and once per exported topic. See the current Pricing tab before running.

**Do I need a Douyin account?** No. The Actor reads the public hot-search response.

**Does it return every Douyin board?** No. It returns the verified public main hot list and its embedded rising strip only.

### Related Actors

- [TikTok Sound Scraper](https://apify.com/fetch_cat/tiktok-sound-scraper)
- [TikTok Video Scraper](https://apify.com/fetch_cat/tiktok-video-scraper)
- [TikTok Hashtag Scraper](https://apify.com/fetch_cat/tiktok-hashtag-scraper)
- [Bilibili Video Search Scraper](https://apify.com/fetch_cat/bilibili-video-search-scraper)
- [Google Trends Scraper](https://apify.com/fetch_cat/google-trends-scraper)

### Support

Open an issue on this Actor's Apify page with the input and approximate run time if a public source response changes.

# Actor input Schema

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

Maximum ranked topics to save, including rising topics when enabled.

## `includeRisingTopics` (type: `boolean`):

Also return Douyin's public 实时上升热点 (real-time rising) strip.

## Actor input object example

```json
{
  "maxItems": 20,
  "includeRisingTopics": true
}
```

# Actor output Schema

## `overview` (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 = {
    "maxItems": 20,
    "includeRisingTopics": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("fetch_cat/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 = {
    "maxItems": 20,
    "includeRisingTopics": True,
}

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

```

## MCP server setup

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