Google Ad Library Ad API

Google Ad Library Ad

主要特性

• 准确解析单条创意将一个路径含 /creative/ 的 adstransparency.google.com URL 解析为最多一条标准化公开广告记录，不会将请求扩大为搜索。
• 广告主与创意字段以稳定广告结构返回创意标识、公开来源 URL、可用文本、广告主引用、目标链接和格式。
• 投放范围信息保留可用的开始与结束日期、国家、展示平台，并仅在来源数据可安全标准化时提供单值展示次数。
• 标准化媒体素材提供可用图片或视频的地址、缩略图、尺寸和时长，同时省略缺失的可选值。

参数

如何使用

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

1. 准备一个 adstransparency.google.com 上的 http 或 https URL，路径必须包含 /creative/。
2. 将 url POST 到 /v1/google-ad-library/ad，并保存返回的 task_id。
3. 轮询 /v1/tasks/{task_id}，直到任务成功或失败。
4. 读取 data.results.items；详情操作最多返回一条记录，因此 has_more 通常为 false，next_cursor 通常为 null。

curl -X POST "https://api.socq.ai/v1/google-ad-library/ad" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://adstransparency.google.com/advertiser/AR01614014350098432001/creative/CR10449491775734153217"}'

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

最佳使用场景

• 补全选定创意： 使用创意 ID、广告主引用、文案、目标链接、格式、媒体和来源 URL，完善此前发现的广告记录。
• 复核公开投放证据： 比较可用日期、国家、展示平台和展示次数，记录已知创意曾在何时何地公开展示。
• 归档创意快照： 保存标准化文本、媒体、广告主、投放、目标链接和 collected_at 字段，供后续比较不同时间点。

使用建议

• 提交完整创意 URL，不要只填 CR 标识或广告主 URL，确保主机名和 /creative/ 路径通过校验。
• 区分任务成功但没有记录与供应服务失败；被移除、受限或当前不可用的创意可能无法形成可用记录。
• 将投放、文本、目标链接、广告主、展示次数和媒体作为可空字段处理，不要把缺失的公开值转换为零或推断性结论。
• 需要发现广告主或枚举广告时使用对应搜索与公司广告接口；该详情操作只解析提交的创意。

相关 API