Company Search API

公開連携の正面口は POST /api/signal-foundry/search です。 GET /api/signal-foundry/companies は、同じ決定的な検索を実行する本体と既存 caller 向けの互換 path です。 どちらも受け取った query と filter を実行し、自然文から別の条件を補完しません。

なお、API key 経由の検索は、広すぎる自由文検索を制限します。検索が弱いときは、社名の言い換えを増やすのではなく、証券コードや法人番号などの既知の識別子を優先してください。

契約サマリー

このエンドポイントの役割は、社名、証券コード、法人番号、domain などの入力から canonical company_id の候補を返すことです。profile や会社別 Signals へは、ここで選んだ company.company_id を渡してください。

POST の検索リクエスト

curl -s \
  -X POST \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>" \
  -H "Content-Type: application/json" \
  "https://signal-foundry.app/api/signal-foundry/search" \
  --data '{"query":"7203","limit":3}'

会社 ID、証券コード、domain、完全一致する短い社名、明示的な filter は、LLM を 必要としません。285A のような英字を含む新形式の証券コード、jpx_ / cn_ で始まる ID も identifier として扱います。

条件を指定する

POST /api/signal-foundry/search は query を書き換えません。所在地、業種、上場区分、 従業員数などは filters へ明示してください。

curl -s \
  -X POST \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>" \
  -H "Content-Type: application/json" \
  "https://signal-foundry.app/api/signal-foundry/search" \
  --data '{
    "query": "AI求人",
    "filters": {
      "prefecture": ["東京都"],
      "industry_33_code": ["5250"],
      "ai_jobs": true
    },
    "limit": 10,
    "planner_mode": "deterministic"
  }'

Body で指定できる主な field:

planner.mode は compatibility field として deterministic を返し、 planner_runs[] は空配列です。planner_mode: "auto" または "llm" を送った場合は、 warnings[].code に planner_mode_deprecated が入ります。 新しい caller は planner_mode を省略してください。

識別子を明示的に解決する

証券コード、法人番号、domain、社名から canonical ID だけを得たい場合は、POST /api/signal-foundry/resolve を使います。

curl -s \
  -X POST \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>" \
  -H "Content-Type: application/json" \
  "https://signal-foundry.app/api/signal-foundry/resolve" \
  --data '{"identifier_type":"securities_code","identifier":"7203"}'

見る key:

• data.status
• data.company_id
• data.candidates[]
• gaps[]
• error

data.status: "ambiguous" の場合は company_id を確定しません。candidates[] を保持し、別の識別子を追加するか人間に確認します。

GET 互換 path のクエリパラメータ

GET /api/signal-foundry/companies を使っている既存 caller は、次の query parameter を継続できます。新しい連携は POST /search を使ってください。

マッチングの仕組み

このエンドポイントは単純な全文検索ではありません。次の順で会社の候補を集めます。

• 識別子の完全一致
• company_id の完全一致
• 正規化した社名の完全一致
• 正規化した社名の前方一致

さらに relevance を付けて並べ替えます。identifier_matched=true の結果は強く優先され、上場会社はスコアがわずかに加算されます。

has_jobs、ai_jobs、construction、prefecture、min_employees、max_employees、order のいずれかを使う場合は、明示した条件だけが適用されます。サーバーは q から都道府県、業種、求人条件を抽出しません。求人や建設業許可の条件は field で指定し、関連情報は companies[].source_context で確認します。

q を指定しない filter-only browse では、同じ filter の件数取得も実行します。件数を確定できた場合は meta.total_kind: "exact"、対象外またはタイムアウトした場合は "lower_bound" になります。meta.matched_companies を分母に使う前に meta.total_kind を確認してください。

max_employees は現時点で sf_company_source_enrichment_mv の hot path でのみ適用されます。q(自由文検索)または semantic_tag を同時に指定すると、会社検索は company card RPC 経路に切り替わり、そちらには従業員数の上限パラメータがありません。この組み合わせは値を無視して返す代わりに 422 (ok: false, status: "blocked", error.code / gaps[].code = "max_employees_unsupported_on_this_path")を返します。同じコードは、sf_company_source_enrichment_mv 自体が一時的に利用できない場合の fail-closed 応答(不完全なフィルタで plain company index にフォールバックしない)にも使われます。max_employees を使う場合は q / semantic_tag を外すか、prefecture / industry_33_code / listing_status / min_employees / has_website など他の構造化フィルタと組み合わせてください。

min_insured_persons / max_insured_persons は社会保険の被保険者数で会社規模を絞り込みます。被保険者数は従業員数ではありません。会社が届け出た適用事業所単位の被保険者数なので、持株会社は連結従業員数よりはるかに小さい値になり、事業会社は有価証券報告書の従業員数を上回ることがあります。従業員数で絞り込みたい場合は min_employees / max_employees を使ってください。被保険者数を持たない会社は、このフィルタを指定した検索結果には含まれません。値の出所（tsujigawa などの provenance）と観測月は Company Card 側の被保険者数ファクトで確認できます。

このエンドポイントは会社起点です。prefecture は会社所在地の絞り込みであり、求人勤務地の絞り込みではありません。個別の求人一覧を先に出してから会社情報を紐付ける、求人行起点のワークフローは、会社検索とは別の求人検索機能で扱います。

レスポンス

GET /api/signal-foundry/companies でまず見る key:

• object
• status
• companies[].company.company_id
• companies[].company.display_name
• companies[].profile.website_domain
• companies[].query_match.identifier_matched
• companies[].query_match.relevance
• warnings[]
• meta.coverage_warnings
• meta.matched_companies
• meta.total_kind
• meta.returned_companies
• meta.has_more

POST /search だけで見る key

POST /api/signal-foundry/search の公開 response では、上記の会社候補に 加えて次を確認します。GET /api/signal-foundry/companies はこれらを返しません。

• planner.mode
• meta.next_cursor
• meta.has_more
• meta.pagination_supported
• meta.more_results_exist
• meta.results_truncated

{
  "ok": true,
  "object": "company_search",
  "status": "ready",
  "companies": [
    {
      "company": {
        "company_id": "jpx_7203",
        "display_name": "トヨタ自動車",
        "legal_name": "トヨタ自動車株式会社",
        "listing_status": "listed",
        "market_segment": "prime"
      },
      "profile": {
        "website_domain": "global.toyota",
        "website_url": "https://global.toyota",
        "latest_observed_at": "2026-04-30T00:00:00.000Z",
        "observation_counts": {},
        "technologies": []
      },
      "query_match": {
        "identifier_matched": true,
        "relevance": 120
      },
      "source_context": null
    }
  ],
  "warnings": [],
  "meta": {
    "query": "7203",
    "returned_companies": 1,
    "matched_companies": 1,
    "total_kind": "exact",
    "has_more": false,
    "coverage_warnings": []
  }
}

この HTTP レスポンスでは、候補会社は companies[] に入ります。会社を特定する ID は companies[].company.company_id、表示名は companies[].company.display_name で確認します。

meta.total_kind が exact の場合だけ meta.matched_companies を確定総数として扱います。exact は次のいずれかで返ります: company_ids を指定し、free-text q を併用しない確定集合の場合。または、q を指定しない filter-only browse でページ取得と並行実行した companion exact-count query が成功し、かつ後段の絞り込み(ライブな has_website 再判定や現在上場membership の再付与)がその件数に含まれる行を1件も落とさなかった場合(このとき meta.total_count_source は exact_count)。company_ids と q を併用した場合は estimate です。lower_bound は確認済み下限で、meta.total_count_source が lower_bound_fallback になるのは、companion exact-count query がタイムアウト・対象外だった場合、または件数クエリ自体は成功したが後段の絞り込みで対象行が1件でも落ちたためこのレスポンスに限って確定総数を安全に名乗れなくなった場合です。estimate は scan / truncation を含み得る推定です。keyset cursor page で総数を返さない場合は matched_companies: null、total_kind: "unknown" になります。meta.has_more も companion exact-count query が成功した場合はその確定総数から算出され(offset + 返却件数 < 確定総数)、ページの取得件数だけからは判定しません。

warnings[] / meta.coverage_warnings は 0 件の読み違いを防ぐための契約です。求人、建設、Web、semantic tag、未対応条件で weak、pending、no_data、unsupported が出た場合は、該当企業なしと断定せず、source の経路や Company Card、filing の evidence で確認します。財務しきい値を決定的に扱う場合は、自然文 q に残さず Company Query に company_query.v1 を渡します。

CLI での実行

sf search "7203" --json
sf search "AI求人" --prefecture 大阪府 --has-jobs true --json
sf search "AI求人" --industry-33-code 5250 --ai-jobs true --json

CLI でも見る key は同じです。

• companies[0].company.company_id
• companies[0].company.display_name
• meta.returned_companies

Company Card と Signals

会社を先に 1 社解決してから、その会社だけを深掘りする場合は Company Card と必要な Signals を使います。採用、Web、技術、IR、建設業許可などの根拠は、会社単位の JSON として読み、表や CSV はローカルで作ります。

sf company jpx_7203 --json
sf signals jpx_7203 --json

求人明細や建設業許可明細を行として見る場合は、会社情報を紐付けた専用の検索機能で確認します。

sf job search "AIエンジニア" --job-location 大阪 --json
sf construction search --prefecture 大阪府 --json

復旧方法

0 件を「会社が存在しない」と断定しないでください。まず warnings[] と meta.coverage_warnings を確認し、必要なら sf search <query> --json で条件を 短くして候補の company_id を確認してから、Company Card / Signals に進みます。