TikTok Ad Library Search
TikTok Ad Library Search 把一个广告主名称或关键词发送到公开 Ads Library，并沿不透明 cursor 继续请求，直到达到按页对齐的上限或触发上游停止条件。它适用于透明度研究和广告发现，不用于私有活动管理或效果衡量。
主要特性
- 单个聚焦查询用一个必填且非空的广告主名称、品牌词或关键词搜索。
- 按页对齐采集以 12 的倍数请求 12 至 2,000 条结果；最大有效值为 1,992。
- 不透明 cursor 处理沿来源 cursor 采集，直到达到上限、出现空页、结束信号、缺少 cursor 或 cursor 重复。
- 标准化广告摘要以稳定字段返回标识、广告主、展示日期、投放、落地页、展示、媒体、发布时间和采集时间。
- 保留来源空值公开搜索结果只有摘要或未暴露某个值时，对应字段保持为空。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
query | 必填 | 必填且非空的广告主名称或关键词。仅接受一个 query。 |
results_limit | 可选 | 可选结果上限。默认 12，必须是 12 至 2,000 之间 12 的倍数；最大有效值为 1,992。 |
如何使用
提交一个 query 和有效的按页对齐上限，轮询异步任务并处理标准化结果页。
- 选择一个广告主名称或关键词；该端点不接受 query 列表。
- 向 /v1/tiktok-ad-library/search POST query 和可选 results_limit。
- 轮询 /v1/tasks/{task_id}，直到任务进入终止状态。
- 读取 data.results.items；结果响应报告有更多页面时继续使用任务结果 cursor。
curl -X POST "https://api.socq.ai/v1/tiktok-ad-library/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"Anysphere","results_limit":12}'
# 轮询 GET /v1/tasks/{task_id}
# 从 data.results.items 读取标准化广告最佳使用场景
- 广告主发现： 查找与所提交广告主或品牌名称关联的受支持公开广告。
- 关键词研究： 为索引内容匹配一个主题词的公开广告建立审阅集合。
- 创意版图审阅： 比较返回记录中的可见主题、媒体引用、广告主标签和展示日期。
- 详情查找队列： 采集公开广告 ID 和来源引用，供详情端点检查选定记录。
使用建议
- 使用具体广告主名称或有辨识度的短语，因为匹配和排序由上游决定。
- 以 12 条为增量设置 results_limit；2,000 虽在通用上限内，但不满足 12 的倍数规则。
- 来源结束、返回空页或重复 cursor 时，实际记录可能少于请求数量。
- 不要假设跨页去重；需要唯一性时，在自己的 pipeline 中使用稳定广告 id 去重。
- 按照来源定义解释 estimated audience 或 impressions，不要把它们当作转化或已验证效果。
- 需要检查一个选定记录时使用 Ad Details；Search 不提供可选详情 enrichment。
相关 API
需要其他类型的 TikTok Ad Library 公开数据时，可以使用以下 API。
- TikTok Ad Library Ad API — 把一个已知 TikTok 公开广告 URL 解析为标准化创意、广告主、投放、落地页、展示、媒体、发布时间和采集字段。