Facebook Ad Library Ad API

Facebook Ad Library Ad

主要特性

• 直接解析 Ad Library URL将带数字 id query 参数的单个公开 /ads/library URL 解析为最多一条标准化广告记录。
• 创意与广告主上下文在公开记录提供时返回广告归档 ID、创意标题与正文、广告主 Page 身份、公开 Page URL、CTA 和目标链接。
• 投放信息与可见信号保留公开记录提供的开始和结束时间、活跃状态、发布平台、国家、Page 点赞数、覆盖、币种和花费。
• 多卡片媒体标准化标准字段选取广告快照或首张卡片中可用的文本，并对快照与卡片中的图片和视频去重，但不将结果描述为完整的创意变体表。

参数

如何使用

提交一个公开 Ad Library URL，跟踪异步任务，并从标准结果结构中读取标准化广告记录。

1. 准备一个公开 Facebook Ad Library URL，路径必须为 /ads/library，query 中必须包含数字 id。
2. 将 url 提交到 /v1/facebook-ad-library/ad，并保存返回的 task_id。
3. 轮询 /v1/tasks/{task_id}，直到任务成功或返回失败。
4. 读取 data.results.items；该接口最多返回一条记录，因此 next_cursor 通常为 null，has_more 通常为 false。

curl -X POST "https://api.socq.ai/v1/facebook-ad-library/ad" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.facebook.com/ads/library/?id=702369045530963"}'

# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items；该操作最多返回一条记录

最佳使用场景

• 补全选定广告： 使用归档 ID、广告主身份、创意标题与正文、媒体、CTA、目标 URL 和输入 URL 补全已有广告记录。
• 审查创意素材与目标链接： 结合展示格式、CTA 文本、CTA 类型和公开目标链接，检查已知广告去重后的图片或视频引用。
• 复核公开投放上下文： 利用活跃状态、开始和结束时间、发布平台、国家以及可用覆盖或花费字段，研究公开投放信息。
• 保存广告时间点快照： 保存创意、广告主、投放、可见信号、输入 URL 和 collected_at，供后续比较同一已知广告。

使用建议

• 提交带完整 /ads/library 路径和数字 id query 参数的 Ad Library URL；Page URL、Page ID、帖子 URL 和裸广告 ID 不是有效输入。
• 输入 URL 语法有效但任务成功后没有记录时，应将其视为广告不可用或未找到的有效结果，不要补造占位记录。
• 将 reach、spend、Page 点赞数、媒体、end_at、广告主主页 URL、CTA 和国家值作为可空公开字段处理，不要把缺失值转换为零。
• 遇到多卡片或多创意广告时，将标准化 name 和 text 作为代表字段，并检查去重后的媒体列表，不要假设它是完整的逐变体表。

相关 API