跳转到主要内容
通过异步 task API 读取 Google Ads 透明度中心,以 JSON 获取竞品投放了哪些 Google 广告。ADS 是独立的引擎。向 taskType ADS 发送 platform google_ads_transparency,并用 action 选择要读取的内容。资料库涵盖所有国家的 Google 搜索、YouTube、展示广告、Google Play、地图和购物广告。要在各广告资料库之间选择,参见 广告资料库对比。
  • search(默认)列出 advertiserId 指定的广告主的广告、advertiserIds 指定的多个竞品的广告,或 domain 指定的网站所链接广告的所有广告主的广告。每条广告带有形式、首次和最后展示的日期以及投放天数,响应末尾附有汇总所返回广告的 summary。
  • advertisers 按名称查找广告主的 advertiserId。
  • ad 打开单条广告:返回广告的文案、视频和落地页,以及资料库公开时按国家和按 Google 展示位置划分的展示次数。
搜索按返回的每 30 条广告收取 0.5 积分。advertisers 和 ad 每次请求收取 0.5 积分。

请求

提交 task 后,轮询 GET /v1/async/task/{id} 或通过 webhook 接收。参见 异步 task。

分析竞品广告

四个请求即可完成一次竞品分析:
  1. 用竞品名称发送 advertisers,得到它的 advertiserId,以及资料库为该名称建议的网站。
  2. 用该 advertiserId 或竞品的 domain 发送 search,列出它的广告。activeDays 显示哪些广告投放最久,mediaType 和 publisherPlatforms 按素材和展示位置划分广告,summary 统计各形式的广告数和每周开始投放的广告数。
  3. 用广告的 libraryId 和 advertiserId 发送 ad,得到文案、视频、触达的国家,对于在欧盟展示的广告,还有按国家和展示位置划分的展示次数。
  4. 用 advertiserIds 发送 search,一次请求比较最多 10 个竞品。

参数

  • action:search(默认)、advertisers 或 ad。
  • query:广告主名称,1 到 100 个字符。advertisers 必须提供,search 和 ad 会拒绝。
  • advertiserId:广告主 ID,例如 AR16396071307843731457。search 需要 advertiserId、advertiserIds 或 domain 之一,ad 必须提供 advertiserId。
  • advertiserIds:1 到 10 个广告主 ID,以数组或逗号分隔的文本发送。一次请求发送 advertiserIds 或 advertiserId 之一。
  • domain:纯域名,例如 nike.com。search 列出链接到该域名的广告,无论由哪个广告主投放。domain 与广告主 ID 不能同时使用。
  • libraryId:广告的素材 ID,例如 CR07264436911983296513。ad 必须提供。
  • country:广告展示的国家,用两位国家代码表示,ALL 表示所有国家(默认)。一次只能指定一个国家。search 读取该字段。
  • publisherPlatforms:广告投放的位置:search、youtube、maps、shopping 或 play。一次只能指定一个值。
  • mediaType:all(默认)、text、image 或 video。
  • startDate、endDate:YYYY-MM-DD,需同时发送。保留在这两天之间至少展示过一次的广告。
  • limit:search 为 1 到 500 条广告(默认 30),advertisers 为 1 到 50 个广告主(默认 30)。
  • cursor:上一次响应的 nextCursor,用于读取其后的广告。
search 读取 advertiserId、advertiserIds、domain、country、publisherPlatforms、mediaType、startDate、endDate、limit 和 cursor。advertisers 读取 query 和 limit,ad 读取 advertiserId 和 libraryId。资料库无法搜索的字段(如 pageId、activeStatus 或 sortBy),或该操作不读取的字段,会以 400 VALIDATION_ERROR 拒绝,details 会指明字段。

比较竞品

advertiserIds 在一次请求中列出最多 10 个广告主的广告。响应的 summary 统计每个广告主的广告数,因此一次请求就能看出谁投放的广告最多。

读取更多广告

资料库的一页最多包含 100 条广告,因此 limit 超过 100 时,一次请求会读取多页。还有更多广告可读时,响应带有 nextCursor。把它作为 cursor 与同一搜索一起发送,即可收到后续广告,同样最多 limit 条。资料库没有更多广告时,nextCursor 为 null。 游标只能用于返回它的那次搜索:advertiserId、advertiserIds、domain、country、publisherPlatforms、mediaType 或日期范围不同,会以 400 VALIDATION_ERROR 拒绝,而 limit 可以改变。

查找广告主

action advertisers 返回名称与 query 匹配的广告主,与资料库搜索框的建议一致。把你选中的 advertiserId 发送出去,即可搜索该广告主的广告。
每个广告主包含 advertiserId、advertiserName、country(广告主注册所在的国家)、verified、adCountRange(资料库给出的该广告主广告数范围,min 和 max)和 libraryUrl,后者在透明度中心打开该广告主。资料库给出的是范围,所以 adCount 为 null。domains 列出资料库为该名称建议的网站,search 以 domain 接收。没有对应广告主的名称会以空的 advertisers 完成。广告主搜索只接收 query 和 limit,收取 0.5 积分。

搜索响应示例

  • 响应会原样返回 platform、action、country、advertiserId、advertiserIds 或 domain,以及你传入的筛选条件。
  • totalCountRange 是资料库对匹配广告数的估计,以 min 和 max 给出。totalCount 为 null。returnedCount 统计 ads 中的广告数,资料库还有更多广告时 hasMore 为 true,可用 nextCursor 继续读取,libraryUrl 在透明度中心打开同一搜索。
  • 每条广告包含 position、libraryId、libraryUrl、advertiserId、advertiserName、format(TEXT、IMAGE 或 VIDEO)、width、height、images、videos、startDate、endDate、activeDays、isActive 和 landingDomain。
  • startDate 和 endDate 是资料库展示该广告的第一天和最后一天(UTC 日期)。activeDays 是从 startDate 到 endDate 的天数,两个日期都计入;资料库没有给出 startDate 时为 null。资料库只公布广告最后一次展示的时间,不说明是否仍在投放,所以最后展示日期是今天或昨天的广告,isActive 为 true。
  • landingDomain 是广告落地页的主机名,转为小写并去掉 www.;资料库没有给出时为 null。
  • 许多文字广告以图片形式出现:images 保存资料库绘制的广告链接,文案在 ad 中。title、body、ctaText 和 linkUrl 在搜索中为 null,广告预览中有的由 ad 填充。impressions 对在欧盟展示的广告由 ad 填充。platforms、targeting、payer 和 utm 为 null。
  • summary 统计本次响应中的广告:ads、activeAds、advertisers(广告最多的 10 个:advertiserId、advertiserName、ads)、formats、landingDomains(广告最多的 10 个)、oldestStartDate、newestStartDate 和 medianActiveDays。它还包含 launchesByWeek(每个 ISO 周开始投放的广告数,按周从早到晚)和 longestRunning(activeDays 最大的 5 条广告)。limit 为 500 的搜索汇总 500 条广告,用 cursor 读取的每一页都带有该页广告的汇总。
  • 广告的图片链接(tpc.googlesyndication.com)未签名,保持可访问。ad 的预览链接已签名,可能过期。
  • 没有匹配广告的搜索会以空的 ads 和广告数为 0 的 summary 完成。

资料库保留的范围

  • 资料库展示所有国家的广告。广告在最后一次展示后保留约 12 个月。
  • 在欧盟展示的广告带有展示次数:广告整体的范围、每个国家的范围(含首次和最后展示的日期)以及每个 Google 展示位置的范围。在其他地区展示的广告带有触达的国家和最后展示的日期。对于这些广告,ad 从广告主的广告列表读取首次展示日期(和 activeDays),与 search 返回的值相同;只有当广告不在它所触达国家的列表前 800 条广告中时,startDate 和 activeDays 才为 null;debug.dates 为 detail、search 或 not-found。
要保留竞品的广告历史,请定期(例如每天)搜索其广告并存储。

打开单条广告

action ad 打开你发送的 libraryId 和 advertiserId 对应的广告,两者都来自搜索结果。它返回广告、广告主和资料库为该广告公开的透明度信息。
  • ad 包含搜索广告的字段,外加广告预览中的文案:title、body、ctaText、displayUrl、linkUrl、longTitle、channelName、address 和 merchant(广告有的才会出现),以及 videos(url、previewUrl)。previewKind 指明广告的类型:text(搜索)、local(地图,带 address)、display(展示广告和 YouTube)或 shopping(带 merchant)。previewText 列出预览中的文字,previewUrl 打开预览。
  • reachedCountries 以 ISO 代码列出广告展示过的国家。
  • impressions(min、max)是资料库为在欧盟展示的广告公开的展示次数范围。在欧盟以外为 null。
  • advertiser 包含 advertiserId、advertiserName 和 libraryUrl。
  • transparency 包含广告的 startDate、endDate 和 impressions,它的 surfaces(每个 Google 展示位置的 surfaceId 和展示次数范围;platform 仅在已知的展示位置 SEARCH 和 MAPS 上给出名称),以及 countries,每个国家各有自己的 startDate、endDate、impressions 和 surfaces。对于在欧盟以外展示的广告,transparency 列出国家及其最后展示的日期,资料库只为欧盟提供的日期和展示次数在那里为 null(广告自身的 startDate 改从广告列表读取)。
  • variants 列出资料库保留的该广告的各种渲染:width、height、imageUrl 和 previewUrl。
  • 资料库不公开定向,所以 platforms 和 targeting 为 null。
  • 资料库没有对应广告的 libraryId 会以 PAGE_UNAVAILABLE 失败。

价格

搜索开始时,按 limit 所要求的每 30 条广告预留 0.5 积分,按实际返回的每 30 条广告收取 0.5 积分,最少 0.5 积分。默认搜索(30 条广告)收取 0.5 积分,limit 为 500 的搜索预留 8.5 积分。advertisers 和 ad 每次请求收取 0.5 积分。只对已完成的请求收费。

相关