Facebook Ad Library Search API

Facebook Ad Library Search

主要特性

• 关键词与完整短语匹配提交一个非空 query，并选择无序关键词或完整短语匹配方式，控制哪些公开广告符合条件。
• 搜索筛选与排序可按广告类型、国家、投放状态、媒体类型和日期范围筛选，并使用支持的展示量或相关性排序。
• 标准化广告与广告主记录以一致结构返回广告归档身份、公开来源 URL、广告主 Page 上下文、创意标题、正文和采集时间。
• 创意、投放与公开上下文保留可用图片或视频、开始与结束时间、活跃状态、发布平台、国家、CTA、目标链接和可见指标。
• 限定数量并自动去重可请求 20 到 2,000 条结果，并在可用结果页中按广告归档 ID 或公开广告 URL 仅保存一次重复记录。

参数

如何使用

提交关键词与定义广告样本的筛选条件，再从完成的异步任务中读取全部标准化记录。

1. 准备一个非空 query，并选择所需匹配方式、广告类型、国家、状态、媒体、排序、日期和结果数量。
2. 向 /v1/facebook-ad-library/search POST 请求，并保存返回的 task_id。
3. 轮询 /v1/tasks/{task_id}，直到任务成功或返回失败。
4. 读取 data.results.items；has_more 为 true 时继续使用 next_cursor。

curl -X POST "https://api.socq.ai/v1/facebook-ad-library/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"running shoes","results_limit":100,"country":"US","status":"ACTIVE","media_type":"VIDEO","search_type":"keyword_unordered"}'

# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items；has_more 为 true 时继续使用 next_cursor

最佳使用场景

• 按关键词发现广告： 结合提交的 query、广告 ID、创意文本、广告主名称和公开 URL，建立可追溯的匹配广告集合。
• 比较创意与展示格式： 比较匹配记录中的创意标题、正文、图片、视频、展示格式、CTA、目标链接和发布平台。
• 监测活跃广告： 重复执行已定义的 query，并对比不同观察时间的广告 ID、活跃状态、开始与结束时间、发布平台和采集时间。
• 研究广告主候选： 使用广告主 Page ID、名称、别名、URL、可见 Page 点赞数和匹配创意，识别适合进一步研究的 Page。

使用建议

• 词序会改变含义时使用 keyword_exact_phrase；广告可能调整短语顺序时使用 keyword_unordered。
• 扩大 results_limit 前先设置国家、状态、媒体、广告类型和日期筛选，使保存的样本保持聚焦。
• 将 results_limit 视为采集上限，并持续读取任务结果 cursor，直到 has_more 为 false。
• 重复运行时按广告归档 ID 或公开广告 URL 去重，同时保留 extra.search_query 和 collected_at 作为观察上下文。
• reach、spend、Page 点赞数、结束日期、媒体、CTA 或国家值缺失时，应解释为公开数据未提供，而不是零。

相关 API