# 广告搜索接口

> 2 个平台的 3 个接口，用同一个 Ad 对象返回广告。按关键词或广告主名称在公开广告库里搜广告，按页返回：广告主、文案、图片或视频、落地页、投放位置和起投时间。每次 $0.002 到 $0.004，各接口按自己的价格计费；失败的调用不扣费。

网页版：https://okdata.online/zh/roles/ads-search/

## 各平台接口

| 平台 | 接口 | 路径 | 每页 | 价格 |
|---|---|---|---|---|
| Meta 广告库 | [Meta 广告库搜索](https://okdata.online/zh/apis/meta/ads/search/) | `GET /v1/meta/ads/search` | 30 | $0.004/次 · 每页约 30 条广告 |
| TikTok | [TikTok 广告库搜索](https://okdata.online/zh/apis/tiktok/ads/search/) | `GET /v1/tiktok/ads/search` | 12 | $0.004/次 · 每页约 12 条广告 |
| TikTok | [TikTok 创意中心热门广告](https://okdata.online/zh/apis/tiktok/creative_center/ads/search/) | `GET /v1/tiktok/creative_center/ads/search` | 20 | $0.002/次 · 每页约 20 条广告 |

## 返回的对象：[Ad](https://okdata.online/zh/docs/objects/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 时返回。 |

## 两个平台上的同一个调用

参数一样、翻页方式一样、返回结构一样，只换路径。

```bash
# Meta 广告库
curl -G "https://api.okdata.online/v1/meta/ads/search" \
  -H "Authorization: Bearer $OKDATA_API_KEY" \
  --data-urlencode 'query=portable espresso'

# TikTok
curl "https://api.okdata.online/v1/tiktok/ads/search" \
  -H "Authorization: Bearer $OKDATA_API_KEY"
```

## 常见用途

- 看某个关键词（比如一个品类）下有哪些品牌在投广告。
- 整理一份本行业的广告素材库。
- 看竞品同一个素材会投多久。

## 常见问题

### 能覆盖所有广告吗？

Meta 广告库和 TikTok 广告库是透明度记录，各有自己的地区和广告类型范围。TikTok 创意中心是表现好的广告的展示，不是全部广告，也没有投放日期。

### 能按国家筛选吗？

Meta 搜索和创意中心搜索都可以指定国家。TikTok 广告库收录的是在欧洲展示过的广告。具体参数见各接口页。

### 能下载素材吗？

只要广告库公开了，images 和 videos 里就有素材地址。之后还要用的话，存一份到你自己那边。

## 其他数据类型

- [评论接口](https://okdata.online/zh/roles/posts-comments-list/)
- [热榜接口](https://okdata.online/zh/roles/trends-list/)
- [评论回复接口](https://okdata.online/zh/roles/comments-replies-list/)
- [话题内容接口](https://okdata.online/zh/roles/topics-posts-list/)
- [账号信息接口](https://okdata.online/zh/roles/accounts-get/)
- [账号作品列表接口](https://okdata.online/zh/roles/accounts-posts-list/)
- [内容详情接口](https://okdata.online/zh/roles/posts-get/)
- [内容搜索接口](https://okdata.online/zh/roles/posts-search/)
- [热门内容接口](https://okdata.online/zh/roles/posts-trending/)
- [账号搜索接口](https://okdata.online/zh/roles/accounts-search/)
- [内容数据接口](https://okdata.online/zh/roles/posts-metrics/)
- [社区帖子接口](https://okdata.online/zh/roles/communities-posts-list/)
- [广告详情接口](https://okdata.online/zh/roles/ads-get/)
- [广告主广告列表接口](https://okdata.online/zh/roles/advertisers-ads-list/)
- [字幕接口](https://okdata.online/zh/roles/transcripts-get/)
- [粉丝列表接口](https://okdata.online/zh/roles/accounts-followers-list/)
- [商品详情接口](https://okdata.online/zh/roles/products-get/)
- [商品评价接口](https://okdata.online/zh/roles/products-reviews-list/)
- [商品搜索接口](https://okdata.online/zh/roles/products-search/)
- [达人搜索接口](https://okdata.online/zh/roles/creators-search/)
- [达人详情接口](https://okdata.online/zh/roles/creators-get/)
- [达人粉丝画像接口](https://okdata.online/zh/roles/creators-audience-get/)