> ## 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. # フィルター概要 > Pubrio の検索フィルターの仕組み — 統一されたフィルターエンジン、AND/OR セマンティクス、そしてどちらをいつ使うか。 Pubrio の検索エンドポイント(`/companies/search`、`/people/search`、`/companies/advertisements/search`)は単一のフィルターエンジンを共有しています。リクエストボディを一度組み立てれば、エンドポイントをまたいで同じルールが適用されます — 複数値フィルターの組み合わせ方、ロケーションのマッチング方法、そして `filter_conditions` でデフォルト演算子を上書きする方法も含めて。 ## なぜ統一フィルターエンジンなのか? `technologies`、`verticals`、`founded_dates` といった企業レベルのフィルターは、`/companies/search`、`/people/search`、Monitor の `company_filters` で同一の挙動 — 一度学べば十分です。 デフォルトは OR(いずれか一致)。`filter_conditions` に 1 行追加するだけで、個別のフィルターを AND(すべて一致)に切り替えられます — 他の項目には触れません。 すべてのフィルターは結果が返される前に適用されるため、各ページと総件数はリクエスト全体を反映します。アプリ側の後段フィルタリングは不要です。 [Monitor](/jp/developer-guides/introduction) の `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` リクエスト: ```bash cURL theme={null} 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 }' ``` ```python Python theme={null} 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()) ``` ```javascript Node.js theme={null} 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](/jp/developer-guides/introduction) が既に使っている構造と一致するため、検索と monitor 設定の間でペイロードをそのまま移動できます。 どちらのスタイルもサポートされます。エンジンは処理前にラップ形式をトップレベルに展開し、**同名キーがある場合はトップレベルが勝ちます**: ```json ラップ形式(推奨) theme={null} { "people_titles": ["VP of Engineering"], "company_filters": { "technologies": [10191, 121], "founded_dates": [2015, 2023], "company_locations": ["US"] } } ``` ```json フラット形式(動作も可) theme={null} { "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`(0-1 のフロート) | | `/people/search/similar` | 参照人物/役職 — `people_titles`、`people_search_id`、`linkedin_url`、`linkedin_urls`、`peoples` のいずれか | 参照に最も近い人物 — 各結果に `similarity_score`(0-1 のフロート) | フィルターは類似度の適用 *前* に候補プールを絞ります — そのため `company_locations: ["US"]` と `/people/search/similar` を組み合わせると、その制約下で参照役職に最も近い米国の人物が返ります。これは「これらの条件下で X に似た人物をさらに見つける」というパターンです。 `/companies/search/similar` は `data` を企業の単純な配列として返します — `pagination` オブジェクトはありません。結果のページ送りには `page` と `per_page` を使用します。類似検索は*最良の*マッチを見つける用途で使い、全件列挙には使わないでください。 *** ## AND vs OR — フィルターごとに 1 つだけ決めること 複数値フィルター(`technologies`、`verticals`、`keywords`、`categories` …)は配列を受け付けます。演算子が「マッチ」の意味を決めます: **いずれかの値にマッチ。** 配列が入力と重なる行を返します。 ```json theme={null} { "technologies": ["Python", "PostgreSQL", "Kubernetes"], "is_enable_similarity_search": true } ``` 企業のテックスタックが `Python`、`PostgreSQL`、`Kubernetes` の **いずれか** を含めば結果に含まれます。 用途: 広い網を投げたいとき — 「いずれかに関心がある」「いずれかの国に所在する」など。 **すべての値にマッチ。** 配列がすべての入力値を含む行を返します。 ```json theme={null} { "technologies": [10191, 121], "filter_conditions": [ { "key": "technologies", "operator": "and" } ] } ``` 数値のタグ ID は、`keyword` を指定した `POST /technologies`(およびバーティカルやカテゴリの対応するエンドポイント)から取得します。フリーテキストの名称と AND を組み合わせた場合、企業は列挙したすべての名称にマッチする必要があります。 企業のテックスタックが `[10191, 121]`(Salesforce と HubSpot)を **すべて** 含む場合のみ結果に含まれます。 用途: 精度が必要なとき — 「これらの技術を *すべて* 使っている」「すべてのバーティカルがタグ付けされている」。 `filter_conditions` に列挙されていないフィルターはデフォルト演算子(配列内は OR、別フィルターキー間は AND)を使います。宣言するのはオーバーライドだけで、デフォルトは書かなくて構いません。 *** ## オーバーライドできるキー エンドポイントごとに受け付けるキーセットが異なります。キーは各 `*_filter_conditions` スキーマの OpenAPI enum に由来します: `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` は、フリーテキストやバーティカルより速く候補集合を縮められます。1〜2 個の精密フィルターと組み合わせてから、類似検索に進みましょう。 AND はすべての値が存在することを要求します。10 件のテクノロジーに AND をかけると、ほぼ 0 行になります。AND フィルターは 2〜4 値に抑え、探索クエリは OR で。 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` と `/companies/advertisements/search` では、企業の広告出稿状況 — 出稿している広告の件数、現在アクティブな広告の有無、使用しているプラットフォームやフォーマット、特定の国における他の広告主と比較したランキング — でフィルタリングできます。 | フィルター | 形式 | 対象 | | - | - | - | | `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` | オブジェクト、下記参照 | 1 か国 | 上限や下限を指定しない場合は `null` を使用します — `[1, null]` は「1 以上」、`[null, 500]` は「500 以下」を意味します。 ```json theme={null} { "advertisement_active_ads": [1, null], "advertisement_formats": ["video"] } ``` ### 国内でのランキング `advertisement_country_activity` は、ランク・パーセンタイル・ボリュームスコアを一度に 1 か国へ絞り込みます — ある企業の米国での広告ランクは、ドイツでのランクについては何も語らないため、`country` は必須です: ```json theme={null} { "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 件以上」のように: ```json theme={null} { "advertisement_country_activity": { "country": "US", "rank": [null, 500] }, "advertisement_active_ads": [100, null] } ``` ### 結果の並べ替え `advertisement_country_activity` によるフィルタリングは*どの*企業が返るかを絞り込むだけで、それ自体が並び順を決めるわけではありません。その市場で最大の広告主を先頭にするには、`sort_by: "advertisement_country_rank"` を指定します: ```json theme={null} { "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` は 2 つの日付ウィンドウも受け付けるため、その市場ですでに大きい企業ではなく、広告出稿を*始めた*企業を問い合わせられます: | キー | 意味 | | - | - | | `first_seen` | `[from, to]` — その国で企業が最初に出稿した広告の時期です。これが「この市場に新規参入した」フィルターです。 | | `last_seen` | `[from, to]` — その国で直近に出稿した広告の時期です。逆の問い、つまりどの企業が静かになったかを調べるのに役立ちます。 | 7 月初め以降に日本市場へ参入した企業: ```json theme={null} { "advertisement_country_activity": { "country": "JP", "first_seen": ["2026-07-01", null] } } ``` いずれの端も `null` にして期間を開放できます。日付はリクエストのタイムゾーンで解釈されます。開始日を持たない広告しかない企業は初回検出値を持たず、不明として扱われます — 新規として報告されることはありません。同じオブジェクト内でランキング関連のキーと組み合わせれば、さらに絞り込めます。たとえば、すでに大量に出稿している新規参入企業などです。 *** ## 次のステップ リファレンスページ — サポートされる全キー、デフォルト、コピー可能な AND/OR レシピ。 `/people/search` 内であらゆる企業フィルターを使う。統一エンジンの目玉機能です。 `/companies/search` の完全なリクエスト/レスポンススキーマ。 `/people/search` の完全なリクエスト/レスポンススキーマ。 ダッシュボード側のフィルタリング解説をお探しですか? ナレッジベースの [連絡先のフィルタリングとエクスポート](/jp/knowledge-base/concepts/search-filters) をご覧ください。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.