> ## 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 — по источнику, формату, целевой стране, охвату и активному периоду — и прочитайте данные о креативе, посадочной странице и показах для каждой.

[Advertisement Search](/ru/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
  }'
```

## Когда это использовать

* **Исследование креативов конкурентов** — что говорит конкурент, в каких странах, в каком формате.
* **Намерение (intent)** — компания, только начавшая рекламироваться на новом рынке, выходит на него. Комбинируйте с `target_locations`.
* **Косвенные показатели расходов** — `reach_tiers` и метрические фильтры `advertisement_*` ранжируют компании по объёму рекламы без цифры расходов.

Для итогов и трендов используйте [Advertisement Insights](/ru/api-reference/endpoint/companies/advertisements_insights). Чтобы найти *компании* по их рекламной активности, а не сами объявления, используйте фильтры `advertisement_*` в [Company Search](/ru/api-reference/endpoint/companies/search).

## Источники

| `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"]}`. Возвращаются только объявления, уже связанные с компанией Pubrio, если вы не установите `is_include_unlinked_companies: true`.

## Фильтры

### Источник и формат

| Ключ                                                  | Тип        | Совпадает                                                                                                                                                                                                             |
| ----------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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`. См. [Форматы](/ru/api-reference/enums#formats). |
| `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]`               | Реклама, **работавшая в любой момент** окна, включая объявления, которые начались раньше и всё ещё активны. Это окно использует Advertisement Insights. Объявления без `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` скрывает большинство активных кампаний компании, потому что кампания, запущенная в марте, всё ещё может работать в августе. Используйте `active_dates`, если вам не нужны именно запуски.
</Tip>

### Где было показано

| Ключ                       | Тип        | Совпадает                                                                                                                                                                   |
| -------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `target_locations`         | `string[]` | Страны, в которых показывалось объявление. По умолчанию OR; добавьте `{"key": "target_locations", "operator": "and"}` в `filter_conditions`, чтобы требовать каждую страну. |
| `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="Реклама Meta только в Instagram">
    ```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="Справочник Advertisement Search" icon="code" href="/ru/api-reference/endpoint/companies/advertisements_search">
    Каждый параметр и поле ответа.
  </Card>

  <Card title="Advertisement Insights" icon="chart-column" href="/ru/api-reference/endpoint/companies/advertisements_insights">
    Итоги, уровни охвата и креативы для одной компании за период.
  </Card>

  <Card title="Фильтры рекламной активности" icon="filter" href="/ru/developer-guides/filters/overview#advertising-activity-filters">
    Находите компании по их рекламной активности в Company Search.
  </Card>

  <Card title="Перечисления и константы" icon="list" href="/ru/api-reference/enums#advertisement-search">
    Источники, форматы, платформы и уровни охвата.
  </Card>
</CardGroup>