フィルター概要

Pubrio の検索エンドポイント(/companies/search、/people/search、/companies/advertisements/search)は単一のフィルターエンジンを共有しています。リクエストボディを一度組み立てれば、エンドポイントをまたいで同じルールが適用されます — 複数値フィルターの組み合わせ方、ロケーションのマッチング方法、そして filter_conditions でデフォルト演算子を上書きする方法も含めて。

なぜ統一フィルターエンジンなのか?

1 つのスキーマ、3 つのエンドポイント

technologies、verticals、founded_dates といった企業レベルのフィルターは、/companies/search、/people/search、Monitor の company_filters で同一の挙動 — 一度学べば十分です。

フィルターごとの AND/OR

デフォルトは OR(いずれか一致)。filter_conditions に 1 行追加するだけで、個別のフィルターを AND(すべて一致)に切り替えられます — 他の項目には触れません。

Postgres ネイティブ演算子

配列フィルターはネイティブの Postgres 演算子にコンパイルされます — OR は &&(オーバーラップ)、AND は @>(包含)。インデックスに優しく、アプリ側の後段フィルタリングは不要です。

Monitor でも同じフィルター

Monitor の company_filters ブロックも同じ形を受け付けるため、動作する検索ペイロードはそのまま動作する monitor ペイロードになります。

検索リクエストの構成

すべての検索リクエストは、同じ JSON ボディ内の 3 つのレイヤーから組み立てられます:

レイヤー	配置場所	例
人物フィルター	トップレベルキー	`people_titles`、`management_levels`、`departments`、`people_locations`
企業フィルター	`company_filters: {...}` 内にネスト(推奨) — トップレベルでも受け付け	`technologies`、`verticals`、`founded_dates`、`employees`、`company_locations`
演算子オーバーライド	`filter_conditions` 配列(企業キーを上書きするときは `company_filters` の中に置く)	`[{ "key": "technologies", "operator": "and" }]`

3 つのレイヤーすべてを使う最小限の /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 — フィルターごとに 1 つだけ決めること

複数値フィルター(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 enum に由来します:

企業エンドポイント

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 は企業エンジンの bare 名 — places、exclude_places — を使い、プレフィックス付きの人物 API 名(company_places)ではありません。詳細は人物 + 企業フィルターを参照してください。

パフォーマンスのヒント

インデックス済みカラムで早めに絞り込む

ロケーション、従業員レンジ、founded_dates はインデックス化されており、フリーテキストやバーティカルより速く候補集合を縮められます。1〜2 個の精密フィルターと組み合わせてから、類似検索に進みましょう。

大きな配列で AND を使いすぎない

column @> ARRAY[a, b, c, …] は全要素の存在を要求します。基数が急増し — 平均 3 タグのカテゴリで 10 件の tech に対して AND をかけると、ほぼ 0 行になりフルスキャンを誘発します。AND フィルターは 2〜4 値に抑え、探索クエリは OR で。

フリーテキスト入力には is_enable_similarity_search

slug ID(verticals、technologies、categories)を渡せず、フリーテキストしかない場合は、is_enable_similarity_search: true と similarity_score: 0.7 を設定してください。エンジンがマッチを解決してからフィルター適用 — テキストスキャンよりずっと安価です。

サイズと売上は enum リストよりレンジを優先

employees: [[201, 500], [501, 1000]](レンジの配列)や revenues: [1000000, 5000000](単一の最小/最大レンジ)は長い ID リストより速く、より自然です。

次のステップ

filter_conditions

リファレンスページ — サポートされる全キー、デフォルト、コピー可能な AND/OR レシピ。

人物 + 企業フィルター

/people/search 内であらゆる企業フィルターを使う。統一エンジンの目玉機能です。

企業検索リファレンス

/companies/search の完全なリクエスト/レスポンススキーマ。

人物検索リファレンス

/people/search の完全なリクエスト/レスポンススキーマ。

ダッシュボード側のフィルタリング解説をお探しですか? ナレッジベースの連絡先のフィルタリングとエクスポートをご覧ください。

モニター