Google Ad Library Company Ads API

Google Ad Library Company Ads

主要特性

• 以广告主或域名为起点至少提供一个 Google 广告主 ID 或公司域名；两者同时存在时，其交集行为由上游来源定义。
• 经过校验的库存筛选按主题、地区、日期窗口、Google 展示平台或文本、图片、视频格式缩小公开创意索引。
• 基于游标的采集按每页 40 条跟随来源游标，在达到 40–2,000 条限制、末页、空页或无效重复游标时停止。
• 稳定广告记录返回共享标准化广告结构，并保留为空的列表级详情字段，不虚构创意补全数据。

参数

如何使用

提交一条结构化广告主库存请求，跟踪异步任务，并用返回的创意 URL 选择性获取详情。

1. 选择 advertiser_id 或 domain，并只添加与比较或采集问题相关的筛选条件。
2. 将 results_limit 设为 40–2,000 范围内的 40 倍数，再 POST 到 /v1/google-ad-library/company-ads。
3. 轮询 /v1/tasks/{task_id} 直到任务成功或失败，必要时再翻阅已保存的任务结果。
4. 将 ID 和创意 URL 视为索引记录；需要丰富字段时，把选定 URL 交给独立广告详情操作。

curl -X POST "https://api.socq.ai/v1/google-ad-library/company-ads" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"advertiser_id":"AR01614014350098432001","region":"US","format":"video","results_limit":80}'

# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items，并选择需要详情的创意 URL

最佳使用场景

• 建立选择性详情队列： 枚举一个广告主的创意 ID 和公开 URL，再只为相关记录发起丰富详情请求。
• 比较可观察格式构成： 在一致标识、筛选、数量限制和采集窗口下，统计返回的文本、图片和视频索引记录。
• 复核公开投放窗口： 识别可比日期、地区、主题或 Google 展示平台筛选下的创意记录，不将其视为私有定向数据。

使用建议

• 已经知道目标 Transparency Center 实体时，优先使用核验过的 advertiser_id，而不是宽泛域名。
• 比较不同时期的创意库存时，保持标识、筛选、results_limit 和采集日期一致。
• 由于 get_ad_details 始终为 false，应预期列表级文本、日期、目标链接、展示次数和媒体为空。
• 成功但为空表示该时间点在所提交标识和筛选下没有可用创意，不代表公司从未投放广告。

相关 API