Facebook Ad Library Ad
Facebook Ad Library 广告是包含创意文本、广告主身份、媒体、行动号召、投放时间、活跃状态以及可用覆盖或花费信号的公开广告记录。这些字段可用于补全选定广告、审查创意、监测公开投放信息和比较不同时间点的记录。
主要特性
- 直接解析 Ad Library URL将带数字 id query 参数的单个公开 /ads/library URL 解析为最多一条标准化广告记录。
- 创意与广告主上下文在公开记录提供时返回广告归档 ID、创意标题与正文、广告主 Page 身份、公开 Page URL、CTA 和目标链接。
- 投放信息与可见信号保留公开记录提供的开始和结束时间、活跃状态、发布平台、国家、Page 点赞数、覆盖、币种和花费。
- 多卡片媒体标准化标准字段选取广告快照或首张卡片中可用的文本，并对快照与卡片中的图片和视频去重，但不将结果描述为完整的创意变体表。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
url | 必填 | 必填的公开 Facebook Ad Library 广告 URL。使用规范的 https://www.facebook.com/ads/library/?id={numeric_id} 形式；每次请求只接受一个 URL。 |
如何使用
提交一个公开 Ad Library URL，跟踪异步任务，并从标准结果结构中读取标准化广告记录。
- 准备一个公开 Facebook Ad Library URL，路径必须为 /ads/library，query 中必须包含数字 id。
- 将 url 提交到 /v1/facebook-ad-library/ad，并保存返回的 task_id。
- 轮询 /v1/tasks/{task_id}，直到任务成功或返回失败。
- 读取 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
需要其他类型的 Facebook Ad Library 公开数据时，可以使用以下 API。
- Facebook Ad Library Search API — 按关键词搜索公开广告，并支持匹配方式、广告类型、国家、状态、媒体、排序、日期和结果数量筛选。
- Facebook Ad Library Company Search API — 通过公司或 Page 名称查找广告主 Page 候选，返回 Page ID、分类、图片、可见受众和关联 Instagram 信号。
- Facebook Ad Library Company Ads API — 通过一个广告主 Page ID 采集公开广告，返回创意、投放、市场、媒体、CTA 和可见指标字段。