广告搜索

广告搜索返回 Pubrio 抓取的单条广告，每条广告一行。每一行包含素材（标题、图片或视频、落地页）、投放地区、投放时间，以及来源报告的曝光区间。

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_* 指标筛选器无需花费数据即可按广告量对公司排序。

需要合计和趋势时请使用广告洞察。若要按广告行为查找公司而非广告本身，请使用公司搜索上的 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`。见格式。
`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），用于增量同步。

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

投放地区

键	类型	匹配
`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（抓取时间）排序，最新在前。

一行数据的样子

{
  "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`

"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` 应用的来源

示例

某市场的竞品素材
高曝光的 LinkedIn 广告
仅 Instagram 的 Meta 广告

cURL

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
  }'

cURL

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 上大量投放的公司。

cURL

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
  }'

广告搜索参考

所有参数和响应字段。

广告洞察

单家公司在某个时间窗内的合计、曝光区间和素材。

广告活动筛选器

在公司搜索中按广告行为查找公司。

枚举与常量

来源、格式、平台和曝光区间。

监控

搜索

筛选器

人员

扩张

适用场景

来源

限定到公司

筛选器

来源与格式

文本

日期

投放地区

曝光与规模

增强

分页与排序

一行数据的样子

此端点的 `metadata`

示例

相关

广告搜索参考

广告洞察

广告活动筛选器

枚举与常量

​适用场景

​来源

​限定到公司

​筛选器

​来源与格式

​文本

​日期

​投放地区

​曝光与规模

​增强

​分页与排序

​一行数据的样子

​此端点的 metadata

​示例

​相关

广告搜索参考

广告洞察

广告活动筛选器

枚举与常量

适用场景

来源

限定到公司

筛选器

来源与格式

文本

日期

投放地区

曝光与规模

增强

分页与排序

一行数据的样子

此端点的 `metadata`

示例

相关