Обзор фильтров

Эндпоинты поиска Pubrio (/companies/search, /people/search, /companies/advertisements/search) используют единый движок фильтров. Вы составляете тело запроса один раз, и одни и те же правила действуют на всех эндпоинтах — включая способ комбинирования мультизначных фильтров, сопоставление локаций и переопределение оператора по умолчанию с помощью filter_conditions.

Зачем единый движок фильтров?

Одна схема, три эндпоинта

Фильтры на уровне компании, такие как technologies, verticals и founded_dates, работают одинаково на /companies/search, /people/search и внутри company_filters в мониторах — вы изучаете их один раз.

AND/OR для каждого фильтра

По умолчанию используется OR (совпадает любое). Переведите отдельные фильтры в AND (совпадают все), добавив одну запись в filter_conditions — не затрагивая остальную часть тела запроса.

Фильтрация до пагинации

Каждый фильтр применяется до возврата результатов, поэтому каждая страница и итоговое количество отражают весь ваш запрос. Без постфильтрации на стороне приложения.

Те же фильтры в мониторах

Блок company_filters в Monitors принимает ту же форму, поэтому рабочий payload поиска также является рабочим payload монитора.

Анатомия поискового запроса

Каждый поисковый запрос строится из трёх слоёв в одном 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: {...} — рекомендуемый способ отправки фильтров уровня компании: она визуально отделяет, какие ключи фильтруют человека, а какие — компанию, и соответствует форме, которую уже использует Monitors, поэтому payload’ы без изменений переносятся между конфигурациями поиска и монитора. Оба стиля работают; движок разворачивает обёрнутую форму на верхний уровень перед обработкой, и ключи верхнего уровня побеждают при конфликте:

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

{
  "people_titles": ["VP of Engineering"],
  "technologies": [10191, 121],
  "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`	Каждый результат получает `similarity_score` (float, 0-1)
`/people/search/similar`	Референсный человек/должность — один из `people_titles`, `people_search_id`, `linkedin_url`, `linkedin_urls` или `peoples`	Люди, наиболее близкие к вашему референсу — Каждый результат получает `similarity_score` (float, 0-1)

Фильтры сужают пул кандидатов до применения сходства — поэтому сочетание company_locations: ["US"] с /people/search/similar возвращает наиболее близких людей из США к вашим референсным должностям, что и является паттерном «найти больше похожих на X в этих ограничениях».

/companies/search/similar возвращает data в виде простого массива компаний — объекта pagination нет. Для постраничного обхода результатов используйте page и per_page. Используйте поиск похожих, чтобы найти лучшие совпадения, а не чтобы перечислить каждое.

AND против OR — единственное решение, которое вы принимаете на фильтр

Мультизначные фильтры (technologies, verticals, keywords, categories, …) принимают массив. Оператор определяет, что означает «совпадение»:

OR (по умолчанию)
AND

Совпадает любое значение. Возвращает строки, чей массив пересекается с вводом.

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

Компания включается, если её технологический стек содержит хотя бы одну из Python, PostgreSQL или Kubernetes.Используйте, когда: вам нужен широкий охват — «интересуется любым из этого», «находится в любой из этих стран».

Совпадает каждое значение. Возвращает строки, чей массив содержит каждое значение из ввода.

{
  "technologies": [10191, 121],
  "filter_conditions": [
    { "key": "technologies", "operator": "and" }
  ]
}

Числовые ID тегов берутся из POST /technologies с параметром keyword (и из соответствующих эндпоинтов для вертикалей и категорий). При использовании названий в свободном тексте вместе с AND компания должна совпасть с каждым из перечисленных вами названий.Компания включается, только если её технологический стек содержит все из [10191, 121] (Salesforce и HubSpot).Используйте, когда: вам нужна точность — «использует все из этих технологий вместе», «отмечена всеми этими вертикалями».

Фильтры, не перечисленные в filter_conditions, используют оператор по умолчанию (OR внутри массива, AND между разными ключами фильтров). Вы объявляете только переопределения — никогда значения по умолчанию.

Что можно переопределить

Каждый эндпоинт принимает переопределения для своего набора ключей. Ключи берутся из перечисления OpenAPI на каждой схеме *_filter_conditions:

Эндпоинт компаний

Ключи company_filter_conditions: keywords, verticals, vertical_categories, vertical_sub_categories, technologies, categories, social_media, advertisement_target_locations, job_exclude_locations.

Эндпоинт людей

Ключи people_filter_conditions: keywords, verticals, vertical_categories, vertical_sub_categories, technologies, categories, social_media.

Эндпоинт рекламы

Ключи ads_filter_conditions: target_locations, publisher_platforms.

Фильтры локаций и мест всегда совпадают с любым из перечисленных значений, на каждом эндпоинте. filter_conditions их не меняет.

Советы по производительности

Начинайте с самых узких фильтров

Локации, диапазоны числа сотрудников и founded_dates сокращают набор кандидатов быстрее, чем свободный текст или фильтры по вертикалям. Сочетайте их с одним-двумя точными фильтрами, прежде чем прибегать к поиску по сходству.

Не злоупотребляйте AND на больших массивах

AND требует наличия каждого значения. AND по 10 технологиям возвращает почти ноль строк. Предпочитайте 2-4 значения на фильтр AND; переключайтесь на OR для исследовательских запросов.

Используйте is_enable_similarity_search для свободного текста

Если вы не можете предоставить slug ID (вертикали, технологии, категории) и у вас есть только строки свободного текста, установите 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` по всей компании.

sort_by: "advertisement_country_rank" игнорируется, когда advertisement_country_activity отсутствует, поскольку ранг существует только внутри страны. Передайте is_ascending_order: false, чтобы сначала вывести самых мелких рекламодателей на рынке.

Поиск новых участников рынка

advertisement_country_activity также принимает два интервала дат, поэтому вы можете спросить, кто начал рекламироваться на рынке, а не кто уже крупен на нём:

Ключ	Значение
`first_seen`	`[from, to]` — когда была показана самая ранняя реклама компании в этой стране. Это фильтр «недавно вышла на этот рынок».
`last_seen`	`[from, to]` — когда была показана её самая недавняя реклама в этой стране. Полезно для обратного вопроса: кто затих.

Компании, вышедшие в Японию с начала июля:

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

Любая граница может быть null для открытого интервала. Даты интерпретируются в часовом поясе запроса. Компания, у рекламы которой нет даты начала, не имеет значения первого показа и считается неизвестной — она никогда не отмечается как новая. Комбинируйте с ранговыми ключами в том же объекте, чтобы сузить выборку ещё сильнее, например новые участники, которые уже много тратят.

Следующие шаги

filter_conditions

Справочник — каждый поддерживаемый ключ, каждое значение по умолчанию и готовые к копированию рецепты AND/OR.

People + Company Filters

Используйте любой фильтр компании внутри /people/search. Главная новая возможность единого движка.

Справочник Company Search

Полная схема запроса/ответа для /companies/search.

Справочник People Search

Полная схема запроса/ответа для /people/search.

Ищете описание фильтрации на стороне дашборда? См. Фильтрация и экспорт контактов в базе знаний.

Мониторинг

Поиск

Фильтры

Люди

Экспансия

Зачем единый движок фильтров?

Одна схема, три эндпоинта

AND/OR для каждого фильтра

Фильтрация до пагинации

Те же фильтры в мониторах

Анатомия поискового запроса

`company_filters`: держите ключи уровня компании сгруппированными

Та же форма у вариантов `/search/similar`

AND против OR — единственное решение, которое вы принимаете на фильтр

Что можно переопределить

Эндпоинт компаний

Эндпоинт людей

Эндпоинт рекламы

Советы по производительности

Фильтры активности рекламы

Ранжирование внутри страны

Сортировка результатов

Поиск новых участников рынка

Следующие шаги

filter_conditions

People + Company Filters

Справочник Company Search

Справочник People Search

​Зачем единый движок фильтров?

Одна схема, три эндпоинта

AND/OR для каждого фильтра

Фильтрация до пагинации

Те же фильтры в мониторах

​Анатомия поискового запроса

​company_filters: держите ключи уровня компании сгруппированными

​Та же форма у вариантов /search/similar

​AND против OR — единственное решение, которое вы принимаете на фильтр

​Что можно переопределить

Эндпоинт компаний

Эндпоинт людей

Эндпоинт рекламы

​Советы по производительности

​Фильтры активности рекламы

​Ранжирование внутри страны

​Сортировка результатов

​Поиск новых участников рынка

​Следующие шаги

filter_conditions

People + Company Filters

Справочник Company Search

Справочник People Search

Зачем единый движок фильтров?

Анатомия поискового запроса

`company_filters`: держите ключи уровня компании сгруппированными

Та же форма у вариантов `/search/similar`

AND против OR — единственное решение, которое вы принимаете на фильтр

Что можно переопределить

Советы по производительности

Фильтры активности рекламы

Ранжирование внутри страны

Сортировка результатов

Поиск новых участников рынка

Следующие шаги