按数据类型找接口
广告主广告列表接口
2 个平台的 2 个接口，用同一个 Ad 对象返回广告主的广告。某个广告主在公开广告库里的广告，按页返回：形式、文案、素材、落地页，以及每条首次和最近展示的时间。每次 $0.004，各接口按自己的价格计费；失败的调用不扣费。
广告主广告列表 · 各平台接口
| 平台 | 接口 | 路径 | 每页 | 价格 |
|---|---|---|---|---|
| Meta 广告库 | Meta 广告主的广告 | GET /v1/meta/advertisers/ads/list | 30 | $0.004/次 · 每页约 30 条广告 |
| Google 广告透明中心 | Google 广告主的广告 | GET /v1/google/advertisers/ads/list | 40 | $0.004/次 · 每页约 40 条广告 |
每次 $0.004，各接口按自己的价格计费。失败的调用不扣费。
返回的对象: Ad
上面每个接口返回的字段名和类型都一样。平台不展示的字段返回 null，并在 meta.unavailable 里注明。
| 字段 | 类型 | 含义 |
|---|---|---|
id | string | 广告在广告库里的 ID。 |
url | string | 广告在广告库里的链接。 |
advertiser | AdvertiserRef | 投放广告的广告主。 |
title | string | null | 广告标题（有的话）。 |
text | string | 广告文案，纯文本；没有则为空字符串。 |
format | string | null | 素材形式；dynamic 指平台按观众动态拼装（商品目录广告）。 |
images | string[] | null | 素材图片地址。 |
videos | string[] | null | 素材视频地址。 |
landing_url | string | null | 广告落地页。 |
cta | string | null | 行动按钮文字。 |
platforms | string[] | null | 投放位置，如 facebook、instagram。 |
active | boolean | null | 是否仍在投放。 |
first_shown_at | string | null | 首次展示时间，ISO 8601，UTC。 |
last_shown_at | string | null | 最近展示时间，ISO 8601，UTC。 |
reach | string | null | 广告库公布的触达人数：区间（如 1K-10K）或人数（Meta 广告的欧盟触达）；未公布为 null。 |
ext | object | 平台特有字段，只在 view=full 时返回。 |
两个平台上的同一个调用
参数一样、翻页方式一样、返回结构一样，只换路径。
# Meta 广告库
curl -G "https://api.okdata.online/v1/meta/advertisers/ads/list" \
-H "Authorization: Bearer $OKDATA_API_KEY" \
--data-urlencode 'id=30147264485'
# Google 广告透明中心
curl -G "https://api.okdata.online/v1/google/advertisers/ads/list" \
-H "Authorization: Bearer $OKDATA_API_KEY" \
--data-urlencode 'id=AR17172796163137470465'常见用途
- 自己做投放计划之前，先看竞品正在投的所有广告。
- 每周看看某个品牌又上了哪些新素材。
- 统计一个品牌在各个投放位置上各有多少条广告。
常见问题
- 用什么指定广告主？
- Google 用广告主 ID 或品牌官网域名；Meta 用 Facebook 主页 ID 或品牌名。每个接口页都列了参数。
- 能区分在投和已停投的广告吗？
- 每条广告都带首次和最近展示时间，广告库标明状态时还有 active。拿 last_shown_at 和今天比一比，就能分开。
- 怎么发现新上的广告？
- 把每次查到的广告 id 存下来，没见过的 id 就是新上的。每次检查读几页就是几次调用。