taskType ADS 发送 platform google_ads_transparency,并用 action 选择要读取的内容。资料库涵盖所有国家的 Google 搜索、YouTube、展示广告、Google Play、地图和购物广告。要在各广告资料库之间选择,参见 广告资料库对比。
search(默认)列出advertiserId指定的广告主的广告、advertiserIds指定的多个竞品的广告,或domain指定的网站所链接广告的所有广告主的广告。每条广告带有形式、首次和最后展示的日期以及投放天数,响应末尾附有汇总所返回广告的summary。advertisers按名称查找广告主的advertiserId。ad打开单条广告:返回广告的文案、视频和落地页,以及资料库公开时按国家和按 Google 展示位置划分的展示次数。
advertisers 和 ad 每次请求收取 0.5 积分。
请求
GET /v1/async/task/{id} 或通过 webhook 接收。参见 异步 task。
分析竞品广告
四个请求即可完成一次竞品分析:- 用竞品名称发送
advertisers,得到它的advertiserId,以及资料库为该名称建议的网站。 - 用该
advertiserId或竞品的domain发送search,列出它的广告。activeDays显示哪些广告投放最久,mediaType和publisherPlatforms按素材和展示位置划分广告,summary统计各形式的广告数和每周开始投放的广告数。 - 用广告的
libraryId和advertiserId发送ad,得到文案、视频、触达的国家,对于在欧盟展示的广告,还有按国家和展示位置划分的展示次数。 - 用
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 积分。只对已完成的请求收费。