怎么在 Google 广告透明中心列出某个品牌的全部广告

要做的事：想看某个品牌在 Google 上都投了什么，覆盖搜索、YouTube、展示网络、购物、地图和 Play，以及每条广告是什么时候在线的。透明中心网站只能一条条点开看。先把品牌名换成 Google 的广告主 ID，再一页页列出它的广告。最后得到一张广告表，每条有格式、预览图、首次和最近展示时间，以及回到透明中心的链接。

不需要 Google 账号，也不用登录 Google Ads。每次调用就是带着 key 发一个 HTTPS 请求。

分步操作

第一步：找到广告主 ID

调用Google 广告透明中心广告主搜索，query 填品牌名，country 可选（ISO 国家代码，默认 US）。一次调用最多返回 10 个匹配的广告主，每次 $0.004，每个有：

• id：广告主 ID，AR 后面跟 20 位数字。
• name：Google 验证过的名称，常常是付钱的公司主体，不一定是你熟悉的品牌名。
• region：注册所在的国家或地区。
• ads：透明中心估计的广告数量。

curl -G "https://api.okdata.online/v1/google/advertisers/search" \
  -H "Authorization: Bearer $OKDATA_API_KEY" \
  --data-urlencode 'query=Kettle & Pine' \
  -d country=US

同名的结果出现好几行很常见：一个名称可能对应多个广告主 ID，有的注册在不同地区，有的根本是不相干的公司。挑 region 和 ads 估计值都对得上的那一行，第一次用时打开它的 url 核对一下。这个接口没有第二页，结果不对就换个更准确的查询词。

第二步：列出广告

调用Google 广告主的广告，传 id（第一步拿到的）或 domain（品牌官网域名，比如 kettleandpine.com），二选一。两个都给或都不给会返回 invalid_params，不扣费。

• id：只返回这一个已验证广告主的广告。
• domain：可以跳过第一步，返回指向这个网站的广告。其中可能混有其他广告主，比如经销商或代理在推同一个网站，所以要逐行看 advertiser.name。

两个筛选参数：country（只看在这个国家展示过的广告；不填为全部）和 format（默认 all，可选 text、image、video）。一次调用最多返回 40 条广告，每次 $0.004。每条广告有 id（素材 ID，CR 后面跟 20 位数字）、url、advertiser（id 和 name）、format、预览图 images、first_shown_at 和 last_shown_at。

curl -G "https://api.okdata.online/v1/google/advertisers/ads/list" \
  -H "Authorization: Bearer $OKDATA_API_KEY" \
  -d id=AR09284716350029384715 -d country=US -d format=video

要下一页，就把 page.next_cursor 原样作为 cursor 传回去，直到 page.has_more 为 false。

第三步：用 Python 写

import collections
import csv
import os
import requests

API = "https://api.okdata.online"
HEADERS = {"Authorization": f"Bearer {os.environ['OKDATA_API_KEY']}"}
MAX_PAGES = 4  # 每页一次调用


def get(path, **params):
    body = requests.get(API + path, headers=HEADERS, params=params, timeout=60).json()
    if body["code"] != "ok":
        raise RuntimeError(f"{body['code']}: {body['message']} (charged: {body['charged']})")
    return body


found = get("/v1/google/advertisers/search", query="Kettle & Pine", country="US")["data"]["items"]
advertiser = max(found, key=lambda a: a["ads"] or 0)  # 第一次跑时人工核对一下选得对不对

ads, cursor = [], None
for _ in range(MAX_PAGES):
    body = get("/v1/google/advertisers/ads/list", id=advertiser["id"], country="US", format="video", **({"cursor": cursor} if cursor else {}))
    ads += body["data"]["items"]
    if not body["page"]["has_more"]:
        break
    cursor = body["page"]["next_cursor"]

with open("google_ads.csv", "w", newline="", encoding="utf-8") as f:
    out = csv.writer(f)
    out.writerow(["creative_id", "advertiser", "format", "first_shown", "last_shown", "preview", "url"])
    for a in ads:
        out.writerow([a["id"], a["advertiser"]["name"], a["format"], a["first_shown_at"], a["last_shown_at"], (a["images"] or [""])[0], a["url"]])

by_month = collections.Counter((a["first_shown_at"] or "")[:7] for a in ads)
print(advertiser["name"], len(ads), "ads;", "new per month:", sorted(by_month.items()))

注意事项

• 列表里没有的字段。 标题、落地页、行动按钮、投放位置、视频文件、是否在投和触达人数都为 null，并在 meta.unavailable 里注明。text 通常是空的：很多广告（包括文字广告）只以渲染好的预览图展示，文案就在图里。用视觉模型或 OCR 读一遍 images 就能把文案取回来。
• 有的广告没有预览图。 透明中心没有预览的素材，images 为 null。
• 没有花费和曝光。 透明中心不公布商业广告的这两项数据。
• 没有按渠道筛选。 不能直接按搜索、YouTube 或展示网络筛。文字广告大多是搜索广告，视频广告大多在 YouTube，所以 format 是最接近的替代办法。
• 额外字段。 view=full 会加上 ext.domain，即这条广告对应的网站。
• 重试不会重复扣费。 每次调用带一个 Idempotency-Key 请求头；24 小时内同样的请求配同样的 key，会拿回存好的结果，不再扣费。

完整的导出流程和每个缺口的说明，见怎么把 Google 广告透明中心里竞品的广告导出来。还想同时看这个品牌在 Meta 和 TikTok 上的广告，看怎么查竞品在三个广告库里的广告。

{
  "endpoint": "google.advertisers.search",
  "params": {
    "query": "Stanley"
  },
  "idempotency_key": "<新的 UUID>"
}