scraping-tiktok-videos-by-hashtag

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Scraping TikTok Videos by Hashtag

按Hashtag抓取TikTok视频

Raw video dataset for any TikTok hashtag or keyword. Returns full video metadata including engagement metrics and author info.

针对任意TikTok Hashtag或关键词的原始视频数据集。返回包含互动指标和作者信息的完整视频元数据。

Prerequisites

前置条件

```
APIFY_TOKEN
```
environment variable set
Optional: Apify MCP server installed

```
APIFY_TOKEN
```
环境变量已设置
可选：已安装Apify MCP服务器

Inputs

输入参数

Parameter	Type	Required	Default	Notes
`startUrls`	array	Optional	`[]`	TikTok URLs — user profiles, hashtags, music pages, search, locations
`keywords`	array	Optional	`[]`	Search keywords/terms to find posts
`sortType`	string	Optional	`RELEVANCE`	Sort order for keyword results: `RELEVANCE` , `MOST_LIKED` , `DATE_POSTED`
`location`	string	Optional	—	ISO 3166-1 alpha-2 country code for regional filtering (e.g. `US` , `GB` )
`maxItems`	number	Optional	Unlimited	Maximum posts to return across the run
`includeSearchKeywords`	boolean	Optional	`false`	Add the matched search keyword field to each post
`customMapFunction`	string	Optional	—	JavaScript function to transform each output object

参数	类型	是否必填	默认值	说明
`startUrls`	数组	可选	`[]`	TikTok链接——用户主页、Hashtag页面、音乐页面、搜索页面、地点页面
`keywords`	数组	可选	`[]`	用于查找帖子的搜索关键词/术语
`sortType`	字符串	可选	`RELEVANCE`	关键词搜索结果的排序方式： `RELEVANCE` 、 `MOST_LIKED` 、 `DATE_POSTED`
`location`	字符串	可选	—	用于区域筛选的ISO 3166-1 alpha-2国家代码（例如 `US` 、 `GB` ）
`maxItems`	数字	可选	无限制	本次运行返回的最大帖子数量
`includeSearchKeywords`	布尔值	可选	`false`	为每个帖子添加匹配的搜索关键字字段
`customMapFunction`	字符串	可选	—	用于转换每个输出对象的JavaScript函数

Workflow

工作流程

Progress:
- [ ] Step 1: Normalize hashtag list
- [ ] Step 2: Run tiktok-scraper
- [ ] Step 3: Poll for SUCCEEDED
- [ ] Step 4: Deliver video dataset

进度:
- [ ] 步骤1：标准化Hashtag列表
- [ ] 步骤2：运行tiktok-scraper
- [ ] 步骤3：轮询直至状态为SUCCEEDED
- [ ] 步骤4：交付视频数据集

Step 2: Run the Actor

步骤2：运行Actor

Recommended — run_actor.js (handles waiting, output, and file saving automatically):

bash

undefined

推荐方案 — run_actor.js（自动处理等待、输出和文件保存）：

bash

undefined

Quick answer (prints table to chat)

node scripts/run_actor.js
--actor "apidojo~tiktok-scraper"
--input '{"param": "value"}'

Save as CSV

node scripts/run_actor.js
--actor "apidojo~tiktok-scraper"
--input '{"param": "value"}'
--output YYYY-MM-DD_results.csv --format csv

Save as JSON

node scripts/run_actor.js
--actor "apidojo~tiktok-scraper"
--input '{"param": "value"}'
--output YYYY-MM-DD_results.json --format json

> `APIFY_TOKEN` must be set in environment or `.env` file.

**If Apify MCP is available:**

Tool: apify:run-actor Actor: "apidojo~tiktok-scraper" Input: { "keywords": ["tag1", "tag2"], "maxItems": 100 }


**REST API fallback:**
```bash
curl -X POST \
  "https://api.apify.com/v2/acts/apidojo~tiktok-scraper/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["tag1", "tag2"], "maxItems": 100}'

Save

id

RUN_ID

. Poll until

status = SUCCEEDED

bash

curl "https://api.apify.com/v2/actor-runs/$RUN_ID?token=$APIFY_TOKEN" | grep '"status"'

Fetch results:

bash

curl "https://api.apify.com/v2/actor-runs/$RUN_ID/dataset/items?token=$APIFY_TOKEN&format=json"

node scripts/run_actor.js
--actor "apidojo~tiktok-scraper"
--input '{"param": "value"}'
--output YYYY-MM-DD_results.json --format json

> `APIFY_TOKEN`必须在环境变量或`.env`文件中设置。

**如果Apify MCP可用：**

Tool: apify:run-actor Actor: "apidojo~tiktok-scraper" Input: { "keywords": ["tag1", "tag2"], "maxItems": 100 }


**REST API备选方案：**
```bash
curl -X POST \
  "https://api.apify.com/v2/acts/apidojo~tiktok-scraper/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["tag1", "tag2"], "maxItems": 100}'

保存

id

为

RUN_ID

。轮询直至

status = SUCCEEDED

bash

curl "https://api.apify.com/v2/actor-runs/$RUN_ID?token=$APIFY_TOKEN" | grep '"status"'

获取结果:

bash

curl "https://api.apify.com/v2/actor-runs/$RUN_ID/dataset/items?token=$APIFY_TOKEN&format=json"

Step 3: Handle Edge Cases

步骤3：处理边缘情况

0 results for hashtag: Hashtag may be banned on TikTok or spelled incorrectly. Try alternate spelling.
< 20 results: Hashtag may be very niche — inform user, return what is available.
Duplicate video IDs across hashtags: Deduplicate by
```
videoId
```
field.

Hashtag无结果：该Hashtag可能已被TikTok封禁或拼写错误，请尝试其他拼写方式。
结果少于20条：该Hashtag可能非常小众——告知用户并返回现有结果。
不同Hashtag下存在重复视频ID：通过
```
videoId
```
字段去重。

Output Format

输出格式

undefined

undefined

TikTok Video Dataset: #<hashtag>

TikTok视频数据集：#<Hashtag>

Videos collected: N | Hashtags queried: N

Video ID	Author	Caption (truncated)	Views	Likes	Comments	Shares	Posted
...	...	...	...	...	...	...	...

Available fields: videoId, authorUsername, desc, playCount, diggCount, commentCount, shareCount, createTime, videoUrl, musicTitle, hashtags, isAd

undefined

已收集视频数: N | 查询的Hashtag数量: N

视频ID	作者	标题（截断）	浏览量	点赞量	评论量	分享量	发布时间
...	...	...	...	...	...	...	...

可用字段: videoId, authorUsername, desc, playCount, diggCount, commentCount, shareCount, createTime, videoUrl, musicTitle, hashtags, isAd

undefined

Troubleshooting

故障排除

Banned hashtag returns 0: Some hashtags are restricted by TikTok — try parent category tag. Slow run: TikTok rate-limits heavily;

maxItems: 200

is a safe cap per run.

被封禁的Hashtag返回0条结果：部分Hashtag被TikTok限制，请尝试父类别标签。 运行缓慢：TikTok限制严格；每次运行设置

maxItems: 200

是安全上限。