Facebook Ad Library API
按关键词搜索公开 Facebook 广告、查找广告主 Page、通过 Page ID 采集广告，或获取一条已知广告的标准化创意、媒体、投放、CTA 和目标链接字段。
可用的 Facebook Ad Library API
按关键词发现广告时使用 Search，查找 Page ID 时使用 Company Search，采集该 Page 的广告时使用 Company Ads，获取一条已知公开广告时使用 Ad Details。
可以获取哪些 Facebook Ad Library 数据？
SocQ 返回标准化公开广告与广告主记录，可用于创意研究、竞品监测、广告分析和广告数据集。
广告搜索结果
按关键词或完整短语搜索公开广告，并可按国家、状态、媒体、广告类型、日期、排序和结果数量筛选。
广告主 Page 记录
获取 Page ID、名称、URL、分类、国家、图片、验证状态、可见 Page 点赞数和关联 Instagram 信息。
指定 Page 的广告集合
通过一个数字广告主 Page ID 采集限定数量的去重公开广告，并可使用投放和媒体筛选条件。
广告创意与媒体
获取可用的广告标题、正文、链接说明、展示格式，以及去重后的公开图片或视频引用。
投放与市场信息
保留可用的开始与结束时间、活跃状态、发布平台、国家、覆盖、币种、花费和 Page 点赞数。
CTA 与目标链接
在公开记录提供时获取 CTA 文本和类型、目标 URL、Ad Library URL、广告主身份和采集时间。
SocQ 与 Meta Ad Library API 对比
SocQ 提供开箱即用的公开广告采集工作流；Meta Ad Library API 适合直接访问 Meta 官方广告透明度档案。
| 能力 | SocQ | Meta Ad Library API |
|---|---|---|
| 主要用途 | 搜索公开广告，并采集广告主或广告详情 | 查询 Meta 官方广告透明度档案 |
| 身份验证 | 使用 SocQ API key，无需客户 Facebook OAuth | 需要 Meta app、access token 和 Ad Library 访问权限 |
| 起始输入 | 关键词、公司名称、Page ID 或公开 Ad Library URL | 官方档案查询参数和 Meta 标识符 |
| 创建或管理广告 | 不支持 | 不支持，需使用 Meta Marketing API |
| 返回格式 | 标准化 SocQ 记录 | Meta Graph API 原生对象 |
Facebook Ad Library API 如何工作
四个 API 使用相同的异步任务和结果分页流程。
1. 选择 API 和输入
根据所需记录，从关键词、公司名称、数字 Page ID 或公开 /ads/library URL 开始。
2. 提交并跟踪任务
发送对应的 POST 请求，保存返回的 task_id，并轮询 /v1/tasks/{task_id} 直到处理结束。
3. 读取标准化结果
处理 data.results.items，并在 has_more 为 true 时继续使用 next_cursor。
使用 SocQ API key 鉴权并向 Search 接口提交关键词。其他 Ad Library API 使用相同的任务流程。
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,"status":"ACTIVE"}'
# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items，并在 has_more 为 true 时继续使用 next_cursor常见 Facebook Ad Library API 使用场景
竞品广告监测
跟踪指定广告主 Page 的公开广告，对比不同时间的创意、媒体、投放状态、市场、CTA 和目标链接。
创意与文案研究
搜索产品、品类或品牌词，研究公开广告文案、展示格式、媒体、CTA 和落地页目标链接。
广告主查找
将公司或品牌名称解析为公开 Page ID 和身份字段，再采集聚焦于该 Page 的广告集合。
广告数据集
保存标准化广告 ID、广告主记录、创意字段、投放信息、来源 URL 和 collected_at 时间，用于后续分析。
限制与公开数据边界
Facebook Ad Library 结果是采集时的公开记录。这些 API 不管理广告账号，也不提供私密广告活动表现数据。
- Search 要求一个非空 query；results_limit 默认为 100，可设置为 20 到 2,000 的整数。
- Company Search 接受一个公司或 Page 名称 query，不支持 results_limit，并可能返回多个名称相近的 Page 候选。
- Company Ads 要求一个数字 Page ID；results_limit 可设置为 20 到 2,000，筛选条件可能减少实际返回数量。
- Ad Details 接受一个带数字 id 的公开 facebook.com/ads/library URL，最多返回一条标准化广告记录。
- 当广告、Page 或筛选后的结果在公开来源中不可用时，已完成任务也可能不返回记录。
- reach、spend、currency、媒体、日期、CTA、目标链接和广告主字段可能缺失，不能将缺失值解释为零。
Facebook Ad Library API 常见问题
Facebook Ad Library API 是什么？
Facebook Ad Library API 是 SocQ 提供的一组 API，用于搜索公开广告、查找广告主 Page、采集指定 Page 的广告，以及获取已知公开广告的详情。
应该使用哪个 Facebook Ad Library API？
按关键词发现广告时使用 Search，查找 Page ID 时使用 Company Search，采集该 ID 对应的广告时使用 Company Ads，获取一条已知广告时使用 Ad Details。
可以使用哪些搜索和筛选条件？
Search 接受关键词或完整短语，并支持国家、状态、媒体、广告类型、日期、排序和结果数量筛选。Company Ads 支持针对 Page 广告的投放和媒体筛选。
会返回哪些公开广告数据？
结果可包含广告和广告主身份、创意文本、图片或视频、投放日期、活跃状态、发布平台、国家、CTA、目标链接和公开可见指标。
为什么已完成的请求可能没有结果？
公开来源可能没有与输入匹配的记录，筛选条件可能排除了全部结果，或者请求的广告或 Page 已不再公开可用。
它与 Facebook 社交数据或 Marketplace API 相同吗？
不同。Facebook Ad Library API 与 SocQ 的 Facebook Page、帖子和评论 API 分开提供，也独立于 Facebook Marketplace 商品 API。
Facebook Ad Library 结果如何计费？
Search 广告、Company Search 候选和 Company Ads 记录每条消耗 0.5 积分，Ad Details 每条消耗 0.6 积分；空结果不产生结果费用。