筛选器概览

Pubrio 的搜索端点(/companies/search、/people/search、/companies/advertisements/search)共享同一个筛选引擎。你只需编写一次请求体,相同的规则就会在各个端点上生效 — 包括多值筛选器的组合方式、位置匹配方式,以及如何通过 filter_conditions 覆盖默认操作符。

为什么使用统一筛选引擎?

一套结构,三个端点

technologies、verticals、founded_dates 等公司级筛选器在 /companies/search、/people/search 以及 Monitor company_filters 中行为一致 — 你只需学一次。

按筛选项设置 AND/OR

默认是 OR(任一匹配)。在 filter_conditions 中添加一条记录就能将单个筛选器升级为 AND(全部匹配)— 无需改动其他字段。

原生 Postgres 操作符

数组筛选器编译为原生 Postgres 操作符 — OR 对应 &&(重叠),AND 对应 @>(包含)。索引友好,无需应用层后置过滤。

Monitor 中通用

Monitor 中的 company_filters 块接受相同结构,因此一份能跑通的搜索请求体也能直接用于 monitor。

搜索请求的结构

每个搜索请求由同一个 JSON 请求体中的三层组成:

层级	位置	示例
人员筛选器	顶层字段	`people_titles`、`management_levels`、`departments`、`people_locations`
公司筛选器	嵌套在 `company_filters: {...}` 中(推荐)— 也可放在顶层	`technologies`、`verticals`、`founded_dates`、`employees`、`company_locations`
操作符覆盖	`filter_conditions` 数组(覆盖公司键时放在 `company_filters` 内部)	`[{ "key": "technologies", "operator": "and" }]`

一个最小化的 /people/search 请求,三层都用上:

curl -X POST https://api.pubrio.com/people/search \
  -H "Content-Type: application/json" \
  -H "pubrio-api-key: YOUR_API_KEY" \
  -d '{
    "people_titles": ["VP of Engineering", "CTO"],
    "company_filters": {
      "technologies": ["Kubernetes", "Docker"],
      "is_enable_similarity_search": true,
      "company_locations": ["US"]
    },
    "per_page": 25,
    "page": 1
  }'

import requests

response = requests.post(
    "https://api.pubrio.com/people/search",
    headers={
        "Content-Type": "application/json",
        "pubrio-api-key": "YOUR_API_KEY",
    },
    json={
        "people_titles": ["VP of Engineering", "CTO"],
        "company_filters": {
            "technologies": ["Kubernetes", "Docker"],
            "is_enable_similarity_search": True,
            "company_locations": ["US"],
        },
        "per_page": 25,
        "page": 1,
    },
)
print(response.json())

const response = await fetch("https://api.pubrio.com/people/search", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "pubrio-api-key": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    people_titles: ["VP of Engineering", "CTO"],
    company_filters: {
      technologies: ["Kubernetes", "Docker"],
      is_enable_similarity_search: true,
      company_locations: ["US"],
    },
    per_page: 25,
    page: 1,
  }),
});
console.log(await response.json());

`company_filters`:把公司级键归成一组

company_filters: {...} 包装对象是发送公司级筛选的推荐方式 — 它直观地分开了哪些键筛选人员、哪些键筛选公司,而且与 Monitor 已经在用的结构一致,搜索与 monitor 配置之间的载荷可以直接互相搬迁。两种风格都支持;引擎在处理前会把包装形式摊平到顶层,同名时顶层键优先:

{
  "people_titles": ["VP of Engineering"],
  "company_filters": {
    "technologies": [37, 152],
    "founded_dates": [2015, 2023],
    "company_locations": ["US"]
  }
}

{
  "people_titles": ["VP of Engineering"],
  "technologies": [37, 152],
  "founded_dates": [2015, 2023],
  "company_locations": ["US"]
}

为公司级键添加 filter_conditions 覆盖时,把它放在 company_filters 内部,这样它和它覆盖的键一起。

`/search/similar` 变体使用相同的请求体

POST /companies/search/similar 和 POST /people/search/similar 接受与其非相似版本相同的筛选器请求体(包括 company_filters 包装和 filter_conditions)。每个端点在此之上叠加相似度步骤:

	额外需要	额外返回
`/companies/search/similar`	参照公司 — `domain_search_id`、`domain`、`linkedin_url` 或 `domains`	每条结果带 `similarity_score`(浮点 0-1),按相似度倒序排列
`/people/search/similar`	参照人物/职位 — `people_titles`、`people_search_id`、`linkedin_url`、`linkedin_urls` 或 `peoples` 之一	同上 — 每条结果带 `similarity_score`,按相似度倒序排列

响应外层结构与标准 search 端点一致。筛选器在相似度排名之前先收敛候选集 — 因此把 company_locations: ["US"] 与 /people/search/similar 结合,会返回符合约束的、最接近你参照职位的美国人物,即”在这些条件下找到更多类似 X 的人”的模式。

与标准 /search 端点不同,/search/similar 不会返回精确的 pagination.total_entries — 该值是被截断的,因为相似度搜索按相关性排序,只返回最佳匹配。请使用相似度搜索来寻找最佳匹配,而不是枚举所有结果。

AND vs OR — 每个筛选器只需做一个决定

多值筛选器(technologies、verticals、keywords、categories……)接受数组。操作符决定”匹配”的含义:

OR(默认)
AND

匹配任一值。 返回数组与输入有重叠的行。

{
  "technologies": ["Python", "PostgreSQL", "Kubernetes"],
  "is_enable_similarity_search": true
}

只要公司的技术栈包含 Python、PostgreSQL 或 Kubernetes 中任何一个,就会被纳入结果。编译为 Postgres column && ARRAY[...]。适用于:你想要覆盖广 — “对其中任何一个感兴趣”、“位于任何一个国家”。

匹配每个值。 返回数组包含所有输入值的行。

{
  "technologies": [37, 152, 408],
  "filter_conditions": [
    { "key": "technologies", "operator": "and" }
  ]
}

Numeric tag IDs come from GET /technologies?search_term=python (and similar). Don’t combine is_enable_similarity_search: true with AND on the same key — similarity expands each free-text term into many tag IDs and @> then requires the row to contain all of them, which almost always returns zero.只有公司技术栈包含 [37, 152, 408] 中所有项时才会被纳入。编译为 Postgres column @> ARRAY[...]。适用于:你需要精度 — “同时使用这些技术”、“标签同时包含所有垂直行业”。

未列入 filter_conditions 的筛选器使用默认操作符(数组内为 OR,不同筛选键之间为 AND)。你只需声明覆盖,不需要写默认值。

可覆盖的键

每个端点接受一组不同的键。键名来自每个 *_filter_conditions 模式中的 OpenAPI 枚举:

公司端点

company_filter_conditions 键:keywords、verticals、vertical_categories、vertical_sub_categories、technologies、categories、advertisement_target_locations、advertisement_exclude_target_locations、advertisement_search_terms、places、exclude_places、job_exclude_locations。

人员端点

people_filter_conditions 键(委托给公司引擎):keywords、verticals、vertical_categories、vertical_sub_categories、technologies、categories、places、exclude_places,以及 social_media。

广告端点

ads_filter_conditions 键:target_locations、exclude_target_locations。范围较小,因为广告只按投放国家筛选。

在 /people/search 中,公司级位置的 filter_conditions[].key 使用公司引擎的裸名 — places、exclude_places — 不是带前缀的人员 API 名称(company_places)。详见人员 + 公司筛选器。

性能建议

尽早在已建索引的列上筛选

位置、员工区间和 founded_dates 都已建索引,缩小候选集的速度比文本或垂直筛选更快。先用一两个精确筛选,再考虑相似度搜索。

不要在大数组上滥用 AND

column @> ARRAY[a, b, c, …] 要求所有值都存在。基数增长很快 — 在平均只标 3 个技术标签的类目上对 10 个 tech 做 AND 几乎返回零行,且会触发全表扫描。AND 筛选保持 2-4 个值;探索性查询用 OR。

自由文本输入用 is_enable_similarity_search

如果你拿不到 slug ID(verticals、technologies、categories),只有自由文本字符串,可设置 is_enable_similarity_search: true、similarity_score: 0.7。引擎会先解析匹配再筛选 — 比扫描文本便宜得多。

规模和收入优先用区间而非枚举列表

employees: [[201, 500], [501, 1000]](区间数组)和 revenues: [1000000, 5000000](单个最小/最大范围)比长 ID 列表更快、更地道。

广告活动筛选器

/companies/search 可以按公司的广告活动进行筛选 — 投放了多少广告、当前是否有广告处于活跃状态、使用了哪些平台和形式,以及在特定国家相对于其他广告主的排名情况。POST /companies/advertisements/search 同样支持上述所有筛选器(advertisement_active_ads、advertisement_running_ads、advertisement_total_ads、advertisement_platform_count、advertisement_format_count、advertisement_impressions_estimate、advertisement_formats、advertisement_country_activity)— 只要广告所属公司满足该条件,该广告就会被纳入结果。

筛选器	类型	适用范围
`advertisement_active_ads`、`advertisement_running_ads`、`advertisement_total_ads`	`[min, max]` 范围	所有国家
`advertisement_platform_count`、`advertisement_format_count`	`[min, max]` 范围	所有国家
`advertisement_impressions_estimate`	`[min, max]` 范围	所有国家
`advertisement_formats`	数组 — `image`、`video`、`text`、`carousel`、`dynamic_product`、`document`、`message`、`event`、`article`、`spotlight`、`follow`、`job`、`engagement`	所有国家
`advertisement_platforms`	数组 — `linkedin`、`facebook`、`google`、`tiktok`、`apple`(`meta` 可作为 `facebook` 的别名)	所有国家
`advertisement_publisher_platforms`、`advertisement_exclude_publisher_platforms`	数组 — `facebook`、`instagram`、`messenger`、`threads`、`audience_network`	所有国家
`advertisement_status`	数组 — `currently_running`(有广告记录)、`active_last_30_min`(广告记录在最近 30 分钟内有变化)	所有国家
`advertisement_country_activity`	对象,详见下文	单个国家

使用 null 表示开放边界 — [1, null] 表示”至少为 1”,[null, 500] 表示”500 或更少”。

{
  "advertisement_active_ads": [1, null],
  "advertisement_formats": ["video"]
}

按国家排名

advertisement_country_activity 会将排名、百分位和投放量评分限定在单个国家范围内 — 一家公司在美国的广告排名并不能说明它在德国的排名情况,因此 country 为必填项:

{
  "advertisement_country_activity": {
    "country": "US",
    "rank": [null, 500]
  }
}

rank 的计数方式就像比赛名次一样,从投放量最大的广告主开始向下排列。 1 代表该国投放量最大的广告主,广告投放量下降时,排名数字则上升。要找出投放量最大的广告主,请为 rank 设置一个较低的上限 — [null, 500] 即为前 500 名。筛选 [500, null] 会找出前 499 名之外的所有广告主,这与”大广告主”的含义正好相反。如果你需要一个不受该国广告主数量影响、可跨国家一致比较的指标,可改用 percentile(百分位)代替 — 它的方向相反:数字越高,代表广告主的投放规模越大:[90, null] 即为前 10%。

可以在同一个请求中,将 advertisement_country_activity 与上文中适用于所有国家的筛选器组合使用 — 例如”在美国排名前 500,且公司全球范围内至少有 100 条活跃广告”:

{
  "advertisement_country_activity": { "country": "US", "rank": [null, 500] },
  "advertisement_active_ads": [100, null]
}

对结果排序

按 advertisement_country_activity 筛选只会缩小返回哪些公司的范围,它本身并不决定排序。要让该市场中投放量最大的广告主排在最前,请指定 sort_by: "advertisement_country_rank":

{
  "advertisement_country_activity": { "country": "HK", "rank": [1, 10] },
  "sort_by": "advertisement_country_rank"
}

只要请求中带有 advertisement_country_activity,每家公司都会一并返回它在该国家的排名情况,因此你可以直接展示用于筛选的排名:

字段	含义
`advertisement_country_rank`	在该国家的名次,1 代表投放量最大的广告主。并列会共用同一名次,因此数字可能重复,之后再跳过若干位。
`advertisement_country_percentile`	该公司在该国家超过了多少比例的广告主。
`advertisement_country_active_ads`	归属于该国家的活跃广告数量 — 不是公司全球范围的 `advertisement_active_ads`。

未使用 advertisement_country_activity 时,sort_by: "advertisement_country_rank" 会被忽略,因为排名只存在于某个国家之内。传入 is_ascending_order: false 可让该市场中投放量最小的广告主排在最前。

找出新进入某个市场的公司

advertisement_country_activity 还接受两个日期窗口,因此你可以查询谁开始在某个市场投放广告,而不只是查询谁在那里已经投放量很大:

键	含义
`first_seen`	`[from, to]` — 公司在该国最早投放广告的时间。这就是”新进入该市场”筛选器。
`last_seen`	`[from, to]` — 公司在该国最近一次投放广告的时间。可用于回答相反的问题:谁已经沉寂了。

自 7 月初以来进入日本市场的公司:

{
  "advertisement_country_activity": { "country": "JP", "first_seen": ["2026-07-01", null] }
}

任一端都可以为 null,表示不设边界。日期按请求所在时区解释。广告没有开始日期的公司没有首次投放值,会被视为未知 — 永远不会被报告为新进入。可以在同一个对象中与排名相关的键组合使用,进一步收窄范围,例如查找已经在大量投放的新进入者。

后续步骤

filter_conditions

参考页 — 每个支持的键、每个默认值,以及可复制的 AND/OR 配方。

人员 + 公司筛选器

在 /people/search 中使用任意公司筛选器。统一引擎的标志性新功能。

公司搜索参考

/companies/search 的完整请求/响应结构。

人员搜索参考

/people/search 的完整请求/响应结构。

寻找仪表板侧的筛选教程?请参阅知识库中的筛选与导出联系人。

监控

搜索

筛选器

人员

扩张

为什么使用统一筛选引擎?

一套结构,三个端点

按筛选项设置 AND/OR

原生 Postgres 操作符

Monitor 中通用

搜索请求的结构

`company_filters`:把公司级键归成一组

`/search/similar` 变体使用相同的请求体

AND vs OR — 每个筛选器只需做一个决定

可覆盖的键

公司端点

人员端点

广告端点

性能建议

广告活动筛选器

按国家排名

对结果排序

找出新进入某个市场的公司

后续步骤

filter_conditions

人员 + 公司筛选器

公司搜索参考

人员搜索参考

​为什么使用统一筛选引擎?

一套结构,三个端点

按筛选项设置 AND/OR

原生 Postgres 操作符

Monitor 中通用

​搜索请求的结构

​company_filters:把公司级键归成一组

​/search/similar 变体使用相同的请求体

​AND vs OR — 每个筛选器只需做一个决定

​可覆盖的键

公司端点

人员端点

广告端点

​性能建议

​广告活动筛选器

​按国家排名

​对结果排序

​找出新进入某个市场的公司

​后续步骤

filter_conditions

人员 + 公司筛选器

公司搜索参考

人员搜索参考

为什么使用统一筛选引擎?

搜索请求的结构

`company_filters`:把公司级键归成一组

`/search/similar` 变体使用相同的请求体

AND vs OR — 每个筛选器只需做一个决定

可覆盖的键

性能建议

广告活动筛选器

按国家排名

对结果排序

找出新进入某个市场的公司

后续步骤