google-ad-library/
company-ads

按广告主 ID 或域名枚举筛选后的公开 Google Ads Transparency Center 创意记录,返回标准化创意身份、来源 URL、投放、格式和可用详情字段。

Google Ad Library Company Ads API

广告主创意库存
每页 40 条
可筛选创意索引
每条结果 0.5 积分
等待提交
等待提交

填写参数并发送请求,任务状态和标准化结果会显示在这里。

README

由 SocQ 维护 · 更新于

Google Ad Library Company Ads

Google Ads Transparency Center 创意库存可以从选定广告主 ID 或公司域名开始枚举,并通过公开查询条件缩小范围。由于该操作关闭逐条广告详情补全,创意标识和来源 URL 是最可靠的列表级字段。

Google Ad Library Company Ads API 主要特性

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

Google Ad Library Company Ads API 参数

参数必填描述
domain必填(至少一项)公司网站域名,例如 lululemon.com。domain 与 advertiser_id 至少填写一个;域名匹配可能跨多个广告主记录。
advertiser_id必填(至少一项)Google Transparency Center 广告主标识,通常以 AR 开头。advertiser_id 与 domain 至少填写一个。
topic可选可选公开来源主题筛选:all 或 political。筛选行为和覆盖范围由来源定义。
region可选可选地区代码,例如 US,作为公开查询上下文转发,并非完整定向定义。
start_date可选可选的 YYYY-MM-DD 来源日期筛选;同时填写两个日期时,不得晚于 end_date。
end_date可选可选的 YYYY-MM-DD 来源日期筛选;同时填写两个日期时,不得早于 start_date。
platform可选可选 Google 展示平台:google_maps、google_play、google_search、google_shopping 或 youtube。
format可选可选创意格式:text、image 或 video。相同或相似创意仍可能以不同记录出现。
results_limit可选最多保存的创意记录数。默认 40,接受 40 到 2,000 的整数,且必须为 40 的倍数。

如何使用 Google Ad Library Company Ads API

提交一条结构化广告主库存请求,跟踪异步任务,并用返回的创意 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

Google Ad Library Company Ads API 最佳使用场景

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

Google Ad Library Company Ads API 使用建议

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

除了 Google Ad Library Company Ads API,需要其他类型的 Google Ad Library 公开数据时,可以使用以下 API。

  • Google Ad Library Ad API — 通过 URL 获取一条已知公开 Transparency Center 创意,返回广告主、文案、媒体、投放、地区、格式、目标链接和展示次数字段。
  • Google Ad Library Advertiser Search API — 按 query 和可选 region 发现公开 Transparency Center 广告主候选,返回身份、网站、徽标、地区和可用广告数量字段。

探索其他平台

还可以将 Google Ad Library 数据与其他已支持社交平台的公开数据结合使用。

Google Ad Library Company Ads API — 常见问题

Google Ad Library Company Ads API 是一个用于按广告主 ID 或域名及可选筛选条件枚举公开 Google Ads Transparency Center 创意索引记录的 API。它返回标准化广告记录,其中创意 ID 和公开 URL 通常比详情字段更可靠。

两者至少提供一个。广告主 ID 通常更精确,域名可能匹配多个公开广告主实体;同时提交时会把两个值一起转发。

它默认是 40,必须为 40 到 2,000 的整数且是 40 的倍数。SocQ 跟随来源游标,并在达到该限制时截断保存记录。

列表请求始终发送 get_ad_details=false。稳定结构字段仍会声明,但不会推断缺失的文本、媒体、目标链接、投放或展示次数。

每条保存的创意记录消耗 0.5 SocQ 积分。预估按 40 条计算并允许超额;成功但为空时只收取配置为零的基础费用。