> ## 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에서 회사가 집행 중인 광고를 소스, 형식, 타겟 국가, 도달, 활성 기간으로 찾고, 각 광고의 크리에이티브, 랜딩 페이지, 노출 데이터를 읽습니다.

[광고 검색](/ko/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_*` 지표 필터로 지출액 없이도 광고량으로 회사를 순위화합니다.

합계와 추세에는 [광고 인사이트](/ko/api-reference/endpoint/companies/advertisements_insights)를 사용하세요. 광고 자체가 아니라 광고 활동으로 *회사*를 찾으려면 [회사 검색](/ko/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`. [형식](/ko/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]`은 라이브 광고가 10개 이상인 회사의 광고를 반환합니다.                               |
| `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`는 필터링할 수 있는 슬러그입니다.
* `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="/ko/api-reference/endpoint/companies/advertisements_search">
    모든 파라미터와 응답 필드.
  </Card>

  <Card title="광고 인사이트" icon="chart-column" href="/ko/api-reference/endpoint/companies/advertisements_insights">
    한 회사의 기간 내 합계, 도달 구간, 크리에이티브.
  </Card>

  <Card title="광고 활동 필터" icon="filter" href="/ko/developer-guides/filters/overview#광고-활동-필터">
    회사 검색에서 광고 활동으로 회사를 찾기.
  </Card>

  <Card title="열거값 및 상수" icon="list" href="/ko/api-reference/enums#광고-검색">
    소스, 형식, 플랫폼, 도달 구간.
  </Card>
</CardGroup>