Douyin Hashtag Search Scraper

EN — Search Douyin hashtags by keyword + date range. Returns a ranked list of matching topics with topic_id (numeric string — this IS the ch_id you pass into the sibling hashtag Actors), heat index, video count, total likes, total plays. One run = one upstream POST call.

ZH — 抖音话题搜索 — 按关键词 + 日期范围搜索抖音话题。 返回匹配的话题列表,每条带 topic_id(数值字符串 — 这就是 ch_id,可以直接传给 hashtag-detail / hashtag-video-list)、热度指数、视频数、总点赞、总播放。一次运行 = 一次上游 POST 请求。

Built for hashtag discovery, trend research, competitor benchmarking, campaign planning, and content ops on Douyin — China's #1 short-video platform.

5 free runs / day. No API key required — the Actor's built-in upstream key is already configured.

Input

Field	Type	Required	Default	Notes
keyword	string	yes	—	Topic keyword, 1-100 chars. Examples: 特朗普, deepseek, 美食.
startDate	string	yes	—	Start date in YYYYMMDD format. Example: 20260901 for 2026-09-01.
endDate	string	yes	—	End date in YYYYMMDD format. Must be >= startDate. Example: 20260911 for 2026-09-11.
appName	string	no	"aweme"	Platform selector. "aweme" = 抖音 (Douyin, default) / "toutiao" = 今日头条 (broader search index).
maxItems	integer	no	100	Cap on items pushed to dataset (1-200). Use to limit noise on broad keywords.

{
  "keyword": "deepseek",
  "startDate": "20260901",
  "endDate": "20260911",
  "appName": "aweme",
  "maxItems": 50
}

Output

The Actor pushes one item per matched topic (capped by maxItems) to the default dataset and writes a SUMMARY record with run details.

{
  "rank": 1,
  "topic_name": "deepseek",
  "topic_id": "1784740573938700",
  "topic_index": 2256692,
  "item_cnt": 17619,
  "digg_cnt": 7101427,
  "play_read_cnt": 169696598,
  "datetime": null,
  "fetched_keyword": "deepseek",
  "fetched_date_range": "20260901_to_20260911",
  "fetched_app_name": "aweme",
  "rawData": { /* full upstream topic_list item */ }
}

⚠️ topic_id is the ch_id. The returned topic_id is the numeric challenge id used by Douyin's hashtag system — paste it directly into douyin-hashtag-detail.chId or douyin-hashtag-video-list.chId to follow up.

SUMMARY record:

{
  "ok": true,
  "keyword": "deepseek",
  "startDate": "20260901",
  "endDate": "20260911",
  "appName": "aweme",
  "requestedMaxItems": 50,
  "requests": 1,
  "totalTopics": 100,
  "itemsPushed": 50,
  "note": "1 Run = 1 upstream request. Pass returned topic_id (= ch_id) into douyin-hashtag-detail / douyin-hashtag-video-list for follow-up."
}

Use it together with the other Douyin Actors

This Actor is part of the 5-Actor Douyin MVP set. Use it together with:

Where in the pipeline	Actor	Use it to
you are here	Douyin Hashtag Search Scraper (you are here)	(this Actor)
step ②	../douyin-hashtag-detail/README.md	pass returned topic_id as chId → rich ch_info (name, view_count, user_count, share info, author)
after / step ③	../douyin-hashtag-video-list/README.md	pass topic_id as chId + walk cursor → full video list under the topic
sister Actor	../douyin-hot-search-list/README.md	board-level trends — 热点榜 / 种草榜 / 娱乐榜 / 社会榜 / 挑战榜
sister Actor	../douyin-live-hot-search-list/README.md	live-stream specific trends (board_type=6) — what is hot on Douyin LIVE right now

You are here: Douyin Hashtag Search Scraper — run this on its own for the upstream use case described above, or chain it with the other 4 Actors for a full Douyin keyword → hashtag → videos → trends pipeline.

Use cases

Persona	Use it for
Influencer marketer	Search hashtags by vertical keyword (e.g. 美食, 健身) to shortlist topic partnerships before deep-diving each
Trend researcher	Run daily/weekly keyword searches with date ranges to surface rising topics before they hit 热点榜
Brand manager	Search for your brand name + product lines to monitor owned-topic performance (item_cnt, play_read_cnt)
Content planner	Generate a 30-day hashtag calendar by keyword + date range, then validate each via step ② / step ③
Competitor analyst	Pull a brand's full hashtag footprint by searching their brand name + variants

Why this Actor exists

Douyin's hashtag system has 100M+ topics but no public search UI for cross-keyword research. This Actor closes that gap — you supply a keyword + a date range, and it returns every matching topic with engagement metrics. The returned topic_id is the bridge to the rest of the Douyin MVP set: feed it into douyin-hashtag-detail for metadata, or douyin-hashtag-video-list for the full video corpus.

Pricing

Free users are limited to 5 runs per day. Paid users (APIFY_USER_IS_PAYING=1) have unlimited runs. The Actor itself adds no markup — you pay the upstream provider per request plus the standard Apify compute unit cost.

Test locally

cd douyin-hashtag-search
UPSTREAM_API_KEY=... UPSTREAM_BASE_URL=<your-upstream-base-url> npm test

• node test/unit.js — 6 unit assertions on normalize / parse / rank / ctx propagation.
• node test/integration.js — 1 live POST call against keyword=deepseek. Returns 100 topics for the given date range. No fixture playback — fixture JSON kept under test/fixtures/ for offline reference only.

Output schema

See .actor/output_schema.json for the full type schema, or read it at runtime via the Apify API.

License

MIT