> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pubrio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 广告搜索

> 按来源、格式、目标国家、曝光量和投放时段查找公司在 LinkedIn、Meta、Google、TikTok 和 Apple 上投放的广告——并读取每条广告的素材、落地页和曝光数据。

[广告搜索](/cn/api-reference/endpoint/companies/advertisements_search)返回 Pubrio 抓取的单条广告，每条广告一行。每一行包含素材（标题、图片或视频、落地页）、投放地区、投放时间，以及来源报告的曝光区间。

```bash theme={null}
curl -X POST https://api.pubrio.com/companies/advertisements/search \
  -H "pubrio-api-key: $PUBRIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": ["stripe.com"],
    "source_types": ["linkedin", "facebook"],
    "active_dates": ["2026-08-01", "2026-08-31"],
    "per_page": 25
  }'
```

## 适用场景

* **竞品素材研究**——竞争对手在说什么、在哪些国家、用什么格式。
* **意向**——刚开始在新市场投放广告的公司正在进入该市场。搭配 `target_locations` 使用。
* **投放量代理指标**——`reach_tiers` 和 `advertisement_*` 指标筛选器无需花费数据即可按广告量对公司排序。

需要合计和趋势时请使用[广告洞察](/cn/api-reference/endpoint/companies/advertisements_insights)。若要按广告行为查找*公司*而非广告本身，请使用[公司搜索](/cn/api-reference/endpoint/companies/search)上的 `advertisement_*` 筛选器。

## 来源

| `source_type` | 说明                                                                                                   |
| ------------- | ---------------------------------------------------------------------------------------------------- |
| `linkedin`    | 格式标签丰富（`Single Image Ad`、`Document Ad` 等）                                                            |
| `facebook`    | 涵盖 Facebook、Instagram、Messenger、Threads 和 Audience Network；用 `publisher_platforms` 缩小范围。接受别名 `meta`。 |
| `google`      | 多为 `text`                                                                                            |
| `tiktok`      |                                                                                                      |
| `apple`       |                                                                                                      |

来源未发布曝光估算的广告 `total_impressions` 为 `null`，且不会匹配 `reach_tiers`。

## 限定到公司

| 键               | 值                                             |
| --------------- | --------------------------------------------- |
| `domains`       | `["stripe.com"]`                              |
| `linkedin_urls` | `["https://www.linkedin.com/company/stripe"]` |
| `companies`     | `["5378845d-…"]`——`domain_search_id` 值        |

不指定公司的搜索也是允许的，例如 `{"target_locations": ["SG"], "source_types": ["linkedin"]}`。除非设置 `is_include_unlinked_companies: true`，否则只返回已关联到 Pubrio 公司的广告。

## 筛选器

### 来源与格式

| 键                                                     | 类型         | 匹配                                                                                                                                                                         |
| ----------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source_types`                                        | `string[]` | `linkedin`、`facebook`、`google`、`tiktok`、`apple`。匹配任一。未知值不匹配任何结果并回显在 `metadata.unsupported_source_types` 中。                                                                 |
| `exclude_source_types`                                | `string[]` | 相同词表，用于排除。                                                                                                                                                                 |
| `advertisement_formats`                               | `string[]` | 规范格式：`image`、`video`、`text`、`carousel`、`dynamic_product`、`document`、`message`、`event`、`article`、`spotlight`、`follow`、`job`、`engagement`。见[格式](/cn/api-reference/enums#格式)。 |
| `publisher_platforms` / `exclude_publisher_platforms` | `string[]` | `facebook`、`instagram`、`messenger`、`threads`、`audience_network`。仅限 Meta 广告。                                                                                                |

### 文本

| 键                              | 类型                    | 匹配         |
| ------------------------------ | --------------------- | ---------- |
| `headlines`                    | `string[]`            | 标题文本，匹配任一。 |
| `search_term` / `search_terms` | `string` / `string[]` | 标题和描述。     |

### 日期

| 键              | 类型           | 匹配                                                                                                      |
| -------------- | ------------ | ------------------------------------------------------------------------------------------------------- |
| `active_dates` | `[from, to]` | 在窗口内**任一时刻正在投放**的广告，包括更早开始且仍在投放的广告。这与广告洞察使用的窗口一致。没有 `started_at` 的广告从 `created_at` 起计。两个日期都必填；UTC 日期边界。 |
| `start_dates`  | `[from, to]` | `started_at` 在窗口内——即那时*上线*的广告。工作区时区的日期边界。                                                               |
| `end_dates`    | `[from, to]` | `ended_at` 在窗口内。工作区时区的日期边界。                                                                             |
| `created_at`   | 日期或 ISO 时间戳  | Pubrio 在该时刻当时或之后抓取（UTC），用于增量同步。                                                                         |

<Tip>
  `start_dates` 会漏掉公司大部分正在投放的广告系列，因为 3 月上线的系列到 8 月仍在投放。除非你明确只要新上线的广告，否则请用 `active_dates`。
</Tip>

### 投放地区

| 键                          | 类型         | 匹配                                                                                                  |
| -------------------------- | ---------- | --------------------------------------------------------------------------------------------------- |
| `target_locations`         | `string[]` | 广告投放的国家。默认 OR；在 `filter_conditions` 中加入 `{"key": "target_locations", "operator": "and"}` 可要求包含所有国家。 |
| `exclude_target_locations` | `string[]` | 要排除的国家。                                                                                             |
| `company_locations`        | `string[]` | 广告主的总部所在国家。                                                                                         |

### 曝光与规模

| 键                                                                                                                                                                                 | 类型           | 匹配                                                                                                             |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------- |
| `reach_tiers`                                                                                                                                                                     | `string[]`   | 广告的曝光区间：`lt_1k`、`1k_10k`、`10k_50k`、`50k_100k`、`100k_500k`、`500k_1m`、`1m_plus`。没有 `total_impressions` 值的广告不会匹配。 |
| `advertisement_active_ads`、`advertisement_running_ads`、`advertisement_total_ads`、`advertisement_platform_count`、`advertisement_format_count`、`advertisement_impressions_estimate` | `[min, max]` | 按**广告主**的合计筛选广告，例如 `advertisement_active_ads: [10, null]` 返回至少有十条在投广告的公司的广告。                                   |
| `advertisement_country_activity`                                                                                                                                                  | 对象           | `{ "country": "US", "rank": [null, 100] }`——该国前 100 名广告主的广告。                                                   |

### 增强

| 键                               | 类型                   | 说明                                                     |
| ------------------------------- | -------------------- | ------------------------------------------------------ |
| `is_realtime_enrichment`        | `boolean`            | 如果搜索无结果，立即抓取来源并重新搜索。仅限限定了公司的搜索。                        |
| `enrichment_mode`               | `default` / `latest` | `latest` 无视缓存，每次调用都重新抓取。                               |
| `is_include_unlinked_companies` | `boolean`            | 同时返回 Pubrio 无法关联到公司记录的广告（`is_company_matched: false`）。 |

### 分页与排序

`per_page`、`page` 和 `is_ascending_order` 与其他搜索一致。行按 `created_at`（抓取时间）排序，最新在前。

## 一行数据的样子

```json theme={null}
{
  "advertisement_id": "58fa840e-08aa-4ac8-a204-8b185fd62f8e",
  "advertisement_search_id": "58fa840e-08aa-4ac8-a204-8b185fd62f8e",
  "created_at": "2026-09-01T02:00:07.068Z",
  "last_modified": "2026-09-01T02:00:07.068Z",
  "started_at": "2026-08-24T00:00:00.000Z",
  "ended_at": "2026-08-31T00:00:00.000Z",
  "title": "Your 2026 peak season prep checklist is here",
  "source_type": "linkedin",
  "advertisement_format": "Single Image Ad",
  "advertisement_format_normalized": "image",
  "is_company_matched": true,
  "advertiser": "Stripe",
  "advertiser_url": "https://www.linkedin.com/company/2135371",
  "advertisement_url": "https://www.linkedin.com/ad-library/detail/1518455034",
  "total_impressions": "< 1k",
  "total_impressions_lower": null,
  "total_impressions_upper": 1000,
  "image_url": "https://buckets.pubrio.com/images/public/….jpg",
  "video_url": null,
  "carousel_images": null,
  "destination_url": "https://stripe.com/industries/retail?trk=…",
  "raw_link_url": null,
  "target_country_codes": ["US"],
  "publisher_platforms": null,
  "companies": {
    "domain_search_id": "5378845d-7726-4817-aba9-ced8c5f41dee",
    "company_name": "Stripe",
    "domain": "stripe.com",
    "country_code": "US",
    "…": "…"
  }
}
```

* 广告仍在投放时 `ended_at` 为 `null`。
* `advertisement_format` 是来源自己的标签；`advertisement_format_normalized` 是可用于筛选的 slug。
* `destination_url` 是还原后的落地页；`raw_link_url` 原样保留点击跟踪链接。
* `total_impressions` 是来源的文本；`_lower` / `_upper` 是解析后的区间。

### 此端点的 `metadata`

```json theme={null}
"metadata": {
  "profile": null,
  "filters": { "domains": ["stripe.com"], "source_types": ["tiktok", "bogus"], "per_page": 25, "language": "en" },
  "ignored_fields": [],
  "applied_source_types": ["tiktok"],
  "unsupported_source_types": ["bogus"],
  "coverage_notes": [{ "source_type": "tiktok", "scope": "eea_uk_ch" }]
}
```

| 键                          | 出现时机               | 含义                                                               |
| -------------------------- | ------------------ | ---------------------------------------------------------------- |
| `ignored_fields`           | 始终                 | 端点丢弃的请求键                                                         |
| `applied_source_types`     | 发送了 `source_types` | 被识别的值                                                            |
| `unsupported_source_types` | 发送了未知值             | 这些值不匹配任何结果                                                       |
| `coverage_notes`           | 适用时                | 所请求来源的覆盖说明                                                       |
| `skipped_source_types`     | 适用时                | `[{ "source_type", "reason" }]`——未针对请求的 `target_locations` 应用的来源 |

## 示例

<Tabs>
  <Tab title="某市场的竞品素材">
    ```bash cURL theme={null}
    curl -X POST https://api.pubrio.com/companies/advertisements/search \
      -H "pubrio-api-key: $PUBRIO_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "domains": ["adyen.com", "checkout.com"],
        "target_locations": ["SG", "AU"],
        "advertisement_formats": ["video", "carousel"],
        "active_dates": ["2026-08-01", "2026-09-04"],
        "per_page": 25
      }'
    ```
  </Tab>

  <Tab title="高曝光的 LinkedIn 广告">
    ```bash cURL theme={null}
    curl -X POST https://api.pubrio.com/companies/advertisements/search \
      -H "pubrio-api-key: $PUBRIO_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "target_locations": ["US"],
        "source_types": ["linkedin"],
        "reach_tiers": ["100k_500k", "500k_1m", "1m_plus"],
        "active_dates": ["2026-08-01", "2026-09-04"],
        "per_page": 25
      }'
    ```

    每行的 `companies.domain_search_id` 都是本月在美国 LinkedIn 上大量投放的公司。
  </Tab>

  <Tab title="仅 Instagram 的 Meta 广告">
    ```bash cURL theme={null}
    curl -X POST https://api.pubrio.com/companies/advertisements/search \
      -H "pubrio-api-key: $PUBRIO_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "domains": ["nike.com"],
        "source_types": ["facebook"],
        "publisher_platforms": ["instagram"],
        "exclude_publisher_platforms": ["facebook"],
        "per_page": 25
      }'
    ```
  </Tab>
</Tabs>

## 相关

<CardGroup cols={2}>
  <Card title="广告搜索参考" icon="code" href="/cn/api-reference/endpoint/companies/advertisements_search">
    所有参数和响应字段。
  </Card>

  <Card title="广告洞察" icon="chart-column" href="/cn/api-reference/endpoint/companies/advertisements_insights">
    单家公司在某个时间窗内的合计、曝光区间和素材。
  </Card>

  <Card title="广告活动筛选器" icon="filter" href="/cn/developer-guides/filters/overview#广告活动筛选器">
    在公司搜索中按广告行为查找公司。
  </Card>

  <Card title="枚举与常量" icon="list" href="/cn/api-reference/enums#广告搜索">
    来源、格式、平台和曝光区间。
  </Card>
</CardGroup>