当每周报告能够显示自上次运行以来新出现了哪些视频时,TikTok 搜索报告就很有用。只需保存已见过的视频 ID,并将新结果添加到 CSV 中即可。下面是一个可复现的 Python 示例,使用 TikTok Scraper API 按关键词搜索视频、解析文档说明的两种响应结构,并维护本地 ID 数据库。
目标:发现新内容,而不是重新检查全部结果
客服团队、市场研究人员或内容分析师可能需要定期收集与某个产品相关的公开视频。如果每次都导出完整结果,重复视频会增加检查难度,而新内容也容易淹没在已处理过的记录中。ID 日志可以让每次运行的结果相互比较:CSV 只包含本流程此前未见的视频,以及响应中返回的主要字段。
这份日志回答的是一个范围有限但实用的问题:当前运行的响应中出现了哪些条目,而它们又不在已保存的 ID 集合中?这对建立人工审核队列,以及将数据导入表格或后续分析都很有帮助。采集结果反映的是 API 针对指定查询返回的内容,本身并不代表 TikTok 上的全部发布内容。
准备工作
- Python 3.8 或更高版本。
- 可访问 TikTok Scraper API,并拥有许可证密钥。
- 一个可重复使用且含义保持不变的查询词,例如产品名称或具体短语。
将密钥保存在环境变量 JSONSCRAPER_TIKTOK_LICENSE_KEY 中,而不要写进脚本文件。下面的示例按照 API 规范,将密钥作为 license_key 查询参数传递。不要将其输出到运行日志中。
export JSONSCRAPER_TIKTOK_LICENSE_KEY="你的密钥"
python -m pip install requests
在 Windows PowerShell 中,可以这样为当前会话设置环境变量:$env:JSONSCRAPER_TIKTOK_LICENSE_KEY="你的密钥"。不要将真实密钥加入 Git 或共享 CSV 文件。
集成:发起搜索并规范化 JSON
搜索视频的文档说明了 GET 路由 /searchVideo,其必需参数为 keyword。请求还可以指定 count、地区、排序方式、时间筛选条件和用于翻页的游标。这个最小示例只使用关键词、请求数量和美国地区。TikTok API 路由参考列出了参数的准确名称。
搜索响应的结构需要特别留意:数组 aweme_list 可能为空,而视频条目也可能位于 search_item_list 中,并嵌套在 aweme_info 下。因此,代码会检查这两种路径,再合并条目并按 aweme_id 去重。这样可以避免 JSON 虽然解析成功,却被错误地转换成空报告。
import csv
import json
import os
from pathlib import Path
from datetime import datetime, timezone
import requests
BASE_URL = "https://tiktok.evelode.com/searchVideo"
KEYWORD = "产品名称"
REGION = "US"
COUNT = 30
STATE_FILE = Path("seen_video_ids.json")
OUTPUT_FILE = Path("new_tiktok_videos.csv")
license_key = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")
if not license_key:
raise RuntimeError("请设置 JSONSCRAPER_TIKTOK_LICENSE_KEY")
response = requests.get(
BASE_URL,
params={
"license_key": license_key,
"keyword": KEYWORD,
"count": COUNT,
"region": REGION,
},
timeout=60,
)
response.raise_for_status()
data = response.json()
# 示例响应包含外层 status 和嵌套的 tiktok 对象。
if "status" in data and data["status"] != "ok":
raise RuntimeError("API 返回的状态不是 ok")
tiktok = data.get("tiktok") or {}
items = list(tiktok.get("aweme_list") or [])
for entry in tiktok.get("search_item_list") or []:
info = entry.get("aweme_info")
if isinstance(info, dict):
items.append(info)
# 当前响应中的唯一条目,保留原有顺序。
current = {}
for item in items:
video_id = item.get("aweme_id")
if video_id:
current[str(video_id)] = item
if STATE_FILE.exists():
seen = set(json.loads(STATE_FILE.read_text(encoding="utf-8")))
else:
seen = set()
new_items = [(video_id, item) for video_id, item in current.items()
if video_id not in seen]
run_time = datetime.now(timezone.utc).isoformat()
fields = ["collected_at_utc", "query", "aweme_id", "created_at",
"author", "description", "share_url", "play_count",
"digg_count", "comment_count", "share_count"]
write_header = not OUTPUT_FILE.exists() or OUTPUT_FILE.stat().st_size == 0
with OUTPUT_FILE.open("a", newline="", encoding="utf-8") as f:
writer = csv.DictWriter(f, fieldnames=fields)
if write_header:
writer.writeheader()
for video_id, item in new_items:
author = item.get("author") or {}
stats = item.get("statistics") or {}
writer.writerow({
"collected_at_utc": run_time,
"query": KEYWORD,
"aweme_id": video_id,
"created_at": item.get("create_time"),
"author": author.get("unique_id") or author.get("nickname"),
"description": item.get("desc"),
"share_url": item.get("share_url"),
"play_count": stats.get("play_count"),
"digg_count": stats.get("digg_count"),
"comment_count": stats.get("comment_count"),
"share_count": stats.get("share_count"),
})
seen.update(current.keys())
STATE_FILE.write_text(json.dumps(sorted(seen)), encoding="utf-8")
print(f"响应中有 {len(current)} 个唯一视频;新增:{len(new_items)}")
如果 JSON 中没有某个值,脚本会在对应单元格中留空,因为单条记录可能缺少某些字段或指标。代码不会用零替代缺失值,也不会把零视为数据缺失。采集时间会单独记录;API 返回的发布时间则来自 create_time 字段。
变更检查的工作方式
- 请求返回指定关键词的搜索结果页。
- 规范化程序从
aweme_list和search_item_list[].aweme_info中收集记录。 - 脚本按视频 ID 去除响应内部的重复项。
- 将这些 ID 与本地 JSON 日志进行比较。
- 将新 ID 添加到 CSV,然后保存所有已见过的 ID,供下次运行使用。


将流程可视化有助于把脚本交接给同事:CSV 是追加式日志,JSON 则保存去重状态。二者可以与代码分开存储,并一起备份。若用于团队或云端运行,请将本地 JSON 文件替换为合适的持久化存储,并确保状态更新具有原子性,以免并行运行互相覆盖。
重复运行与分页
可以通过操作系统计划任务、CI 任务或自动化工作流定期运行脚本。不要在没有记录查询版本的情况下更改关键词:不同查询会形成不同的结果集,混在同一份日志中会增加解读难度。为保持简单,示例脚本只使用一个查询;也可以循环处理多个查询,并在每一行中保留 query 字段。
API 支持使用 cursor 翻阅搜索结果。若要加入分页,请传递上一响应中的游标,将其作为不透明值保存,并在不需要更多页面时停止遍历。count 限定了请求的条目数,但实际记录数量应以响应为准。即使获取了多个页面,它们仍只是搜索结果页,并不能保证覆盖整个平台。
此示例有意不包含文本自动分类,也不试图判断是否存在“趋势”。CSV 可以帮助快速筛出新发现的记录;分析人员随后可以按主题、意图或问题类型进行标注,并人工核查样例。如果接入语言模型,只传递所需的文本字段,并要求模型连同原始 ID 一起返回分类结果,以便验证并与对应记录关联。
检查与常见问题
- HTTP 错误。
raise_for_status()会在 HTTP 状态码不属于成功范围时停止执行。更新状态文件之前,请先检查 API 是否可用、参数是否正确以及账户状态。 - API 状态不是
ok。 如果响应中存在值不同的顶层status字段,脚本会在写入结果前停止。这会保留之前的日志,并避免将错误响应当作空结果。 aweme_list为空。 也要检查search_item_list;代码已兼容这两种结构。- 视频在不同运行中重复出现。 搜索结果页之间存在重叠是正常现象;如果 ID 已保存,这些视频不会再次写入报告。
- 指标缺失。 对应单元格会留空。进行计算时,应区分缺失值与实际为零的值。
- 状态丢失。 脚本会将返回的所有 ID 都视为新内容。请与 CSV 一起备份
seen_video_ids.json,或使用持久化数据库。
自动化运行时,应保存诊断信息,但不要记录密钥:运行时间、HTTP 状态码、API 状态、解析出的记录数以及新增 ID 数量。这样有助于区分“没有新视频”和“请求失败”。若需要日后重新核查响应结构,可以单独归档完整响应;请根据团队需求限制访问权限和保留期限。
结果
运行后,你会得到一份 CSV,其中包含日志尚未记录的视频 ID、描述、链接及可用的公开字段;同时还会生成一份 JSON 状态文件,用于与下一次运行进行比较。这份结果可以作为客服、分析或内容团队的精简待处理队列。有关 API 说明和访问方式,请参阅 TikTok Scraper API 页面;搜索参数的准确名称请以官方路由参考为准。