怎么拉取 TikTok 创意中心热门广告，再到广告库里查某个品牌

要做的事：下周要给某个品类写创意 brief，想从两个角度看 TikTok 上的广告。创意中心的“热门广告”（Top Ads）是 TikTok 自己挑出来的效果好的广告，有点赞和点击率，但没有投放日期。广告库（Ads Library）是在欧洲投放过的广告的透明记录，有投放日期和触达人数区间，但没有效果数据。先用热门广告找出值得研究的钩子和品牌，再打开其中一个品牌的记录，看它在投多少条广告、每条跑了多久。

最后你会得到两张表：一张是热门素材和它们的数据，一张是某个广告主的投放历史。整个过程不需要 TikTok 账号，也不用登录，每次调用就是带着 key 发一个 HTTPS 请求。

分步操作

第一步：搜创意中心热门广告

调用TikTok 创意中心热门广告，query 填关键词。决定结果的是这三个参数：

• country：ISO 国家代码，默认 US。英国是 GB。
• window：回看天数，可选 7、30（默认）或 180。
• sort：relevance（默认，综合排序）或 likes（按点赞）。

一次调用最多返回 20 条广告，每次 $0.002。每条广告有 id、文案 text、品牌名 advertiser.name、视频 videos、封面 images，以及创意中心页面链接 url。加上 view=full，每条广告还会多出 ext.likes、ext.ctr、ext.budget_level、ext.objective、ext.industry 和 ext.duration_seconds，价格不变。

curl -G "https://api.okdata.online/v1/tiktok/creative_center/ads/search" \
  -H "Authorization: Bearer $OKDATA_API_KEY" \
  --data-urlencode 'query=sunscreen' \
  -d country=GB -d window=7 -d sort=likes -d view=full

要第二页，就把 page.next_cursor 原样作为 cursor 传回去；page.has_more 为 false 时说明没有更多了。

第二步：到广告库里打开一个品牌的记录

把第一步里的品牌数一数，挑出你想研究的那个，把名字作为 advertiser 传给TikTok 广告库搜索；也可以用 query 按关键词搜广告库。两个参数只能给一个：两个都给或都不给会返回 invalid_params，不扣费。

一次调用最多返回 12 条广告，每次 $0.004。每条有 advertiser.name、广告标题 text、videos 和 images、first_shown_at 和 last_shown_at、reach（广告库给出的触达人数区间，比如 10K-100K），以及广告库页面链接 url。加 view=full 还有 ext.subject，也就是广告库给这条广告标的类目。

curl -G "https://api.okdata.online/v1/tiktok/ads/search" \
  -H "Authorization: Bearer $OKDATA_API_KEY" \
  --data-urlencode 'advertiser=Sunday Shield Ltd'

这里要用广告库登记的广告主名称，常常是公司主体名，不一定和创意中心显示的品牌名一样。用 advertiser 搜不到时，改用 query 搜品牌名，再按 advertiser.name 把对得上的行留下。

第三步：用 Python 串起来

import collections
import csv
import os
import requests

API = "https://api.okdata.online"
HEADERS = {"Authorization": f"Bearer {os.environ['OKDATA_API_KEY']}"}
PAGES = 2  # 每一步读几页；每页一次调用


def pages(path, params):
    cursor = None
    for _ in range(PAGES):
        body = requests.get(API + path, headers=HEADERS, params={**params, **({"cursor": cursor} if cursor else {})}, timeout=60).json()
        if body["code"] != "ok":
            raise RuntimeError(f"{body['code']}: {body['message']} (charged: {body['charged']})")
        yield from body["data"]["items"]
        if not body["page"]["has_more"]:
            return
        cursor = body["page"]["next_cursor"]


top = list(pages("/v1/tiktok/creative_center/ads/search", {"query": "sunscreen", "country": "GB", "window": "7", "sort": "likes", "view": "full"}))
with open("top_ads.csv", "w", newline="", encoding="utf-8") as f:
    out = csv.writer(f)
    out.writerow(["id", "brand", "caption", "likes", "ctr", "budget_level", "url"])
    for a in top:
        out.writerow([a["id"], a["advertiser"]["name"], a["text"], a["ext"]["likes"], a["ext"]["ctr"], a["ext"]["budget_level"], a["url"]])

brands = collections.Counter(a["advertiser"]["name"] for a in top if a["advertiser"]["name"])
brand = brands.most_common(1)[0][0]
with open("brand_ads.csv", "w", newline="", encoding="utf-8") as f:
    out = csv.writer(f)
    out.writerow(["id", "advertiser", "title", "first_shown", "last_shown", "reach", "url"])
    for a in pages("/v1/tiktok/ads/search", {"advertiser": brand}):
        out.writerow([a["id"], a["advertiser"]["name"], a["text"], a["first_shown_at"], a["last_shown_at"], a["reach"], a["url"]])

注意事项

• 热门广告是精选，不是全量。 这是 TikTok 自己挑的。一个品牌没出现在里面，不代表它没在大量投放；要看品牌到底投过什么，去广告库查。
• 广告库只有欧洲。 广告库记录的是在欧洲投放过的广告。只在美国投放的品牌，在这里可能查不到任何记录。
• 哪些字段是空的。 创意中心的广告没有投放日期、落地页、触达人数和广告主 ID，这些字段为 null，并在 meta.unavailable 里注明原因。创意中心没显示品牌时，品牌名可能是空字符串。ext.objective 和 ext.industry 是 TikTok 内部的键名，比如 campaign_objective_traffic。
• 点击率和预算档位只当信号看。 它们适合在创意中心内部给素材排个先后。做预算还是要看自己的投放数据。
• 想留的视频当天就下载。 视频链接指向 TikTok 的服务器，过一阵可能失效。
• 重试不会重复扣费。 每次调用带一个 Idempotency-Key 请求头。24 小时内同样的请求配同样的 key，会直接拿回上次的结果，meta.replayed 为 true，不再扣费。

想知道 TikTok 官方有没有这类接口，可以看创意中心热门广告能不能用 API 拿。要同时盯一个竞品在 Meta、Google 和 TikTok 上的广告，看怎么查竞品在三个广告库里的广告。

{
  "endpoint": "tiktok.creative_center.ads.search",
  "params": {
    "query": "coffee"
  },
  "idempotency_key": "<新的 UUID>"
}