Douyin Hashtag Search Scraper

✨ What you get

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 Data provider 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.

No API key required. Nothing to configure, and no daily run cap.

💼 Use cases

• Turning a keyword into a list of usable challenge ids — supply keyword plus a startDate / endDate window and every matched topic comes back with topic_id, heat index, item_cnt, digg_cnt and play_read_cnt, where topic_id is exactly the ch_id the other hashtag Actors accept.
• Running a weekly rising-topic check — the same keyword with a rolling seven-day range surfaces topics that are heating up before they reach the main hot search board, which is the point of watching them weekly rather than once.
• Comparing an owned topic against the field — search your brand name plus product-line variants and item_cnt and play_read_cnt show how your challenge stacks up against every other topic matching those terms.
• Planning a content calendar with a verifiable next step — each returned topic_id can be handed straight into the hashtag detail Actor for full metadata or the video-list Actor for the corpus, so a candidate topic is validated before it goes on the calendar.

✅ Who this is for

• Trend researchers — running scheduled keyword-plus-date-range scans to catch topics early.
• Brand managers — watching their own topics and the category they compete in.
• Content planners — building a topic calendar that can be validated topic by topic.
• Competitive analysts — mapping a rival's hashtag footprint across name variants.

❌ Who this is NOT for

• Anyone wanting an open-ended topic search — keyword, startDate and endDate are all required, so there is no "everything trending now" mode. If you want that, the hot search board Actor is the one that takes no window.
• Anyone expecting a broad keyword to be exhaustive — maxItems (1-200) only caps how many rows are pushed; it does not widen the search. A broad term returns a noisy top slice, so narrow the keyword and the date range instead of raising the cap.
• Anyone reading the row's own timestamp — the returned datetime field is null in the output shape, so the only window a row can be attributed to is the fetched_keyword / fetched_date_range pair you supplied. Do not present it as the topic's publish date.
• Video-level analysis — rows are topics, not videos. No video ids, no video URLs, no per-author data, and the topic_id has to be passed into a second Actor to get any of that.
• Pure Douyin measurement with appName: toutiao — that selector switches to the Toutiao index, a broader search index. Metrics collected under it describe a different surface than the one you are trying to benchmark.

📥 Input parameters

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 Data provider 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 Data provider request. Pass returned topic_id (= ch_id) into douyin-hashtag-detail / douyin-hashtag-video-list for follow-up."
}

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

💰 Billing

There is no daily run cap; APIFY_USER_IS_PAYING=1 only sets the billing tier reported in the summary. The Actor itself adds no markup — you pay the data provider provider per request plus the standard Apify compute unit cost.

📚 Resources

cd douyin-hashtag-search
Data provider_API_KEY=... Data provider_BASE_URL=<your-Data provider-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.

MIT

📜 Notes & caveats

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 data provider use case described above, or chain it with the other 4 Actors for a full Douyin keyword → hashtag → videos → trends pipeline.

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.