Search API
Search API の全体像
Search API は、金融機関コード・支店コードをもとに、銀行・支店情報を取得するAPIです。このページでは現行推奨の v3 をベースに、API全体の構成と核になる使い方を説明します。
このページの位置付け
このページは Search API の入口です。実装判断に必要な大枠、主要エンドポイント、v1/v2/v3の違い、filter / freeword / Resolve API β の使い分けを説明します。
各バージョンの完全な仕様、リソース定義、filter構文、fields、sort、ページング、リリースノートは Search API v3 仕様 / v2 仕様 / v1 仕様 を参照してください。OpenAPI は機械可読仕様・コード生成・schema確認用です。
推奨バージョン
| バージョン | 位置付け | 詳細仕様 |
|---|---|---|
| v3 | 現行推奨。新規実装では v3 を利用してください。 | Search API v3 仕様 |
| v2 | 既存システムとの互換用。レスポンス項目名は v3 と一部異なります。 | Search API v2 仕様 |
| v1 | 既存システムとの互換用。金融機関リソースに businessTypeCode / businessType は含まれません。 | Search API v1 仕様 |
filter / freeword / Resolve API β の使い分け
| やりたいこと | 使うAPI/機能 | 判断基準 |
|---|---|---|
| 金融機関コードから銀行情報を取得したい | GET /v3/banks/{code} | コードが既に確定している場合。 |
| 銀行コード・支店コードから支店情報を取得したい | GET /v3/banks/{bankCode}/branches/{code} | 支店コードまで確定している場合。 |
| 特定フィールドで絞り込みたい | filter | hiragana==みずほ のように、対象フィールドと条件が明確な場合。 |
| 検索ボックスのような自由入力で候補を探したい | /v3/freeword/... | ユーザーが入力した文字列から候補一覧を出す場合。 |
| 銀行名・支店名の組み合わせからコード候補を判定したい | Resolve API β | 自動確定できるか、確認が必要かを decision で判定したい場合。 |
v3主要エンドポイント
| 機能 | Method | Path | 詳細 |
|---|---|---|---|
| 金融機関一覧 | GET | /v3/banks | v3仕様 |
| 金融機関取得 | GET | /v3/banks/{code} | v3仕様 |
| 支店一覧 | GET | /v3/banks/{bankCode}/branches | v3仕様 |
| 支店取得 | GET | /v3/banks/{bankCode}/branches/{code} | v3仕様 |
| 金融機関曖昧検索 | GET | /v3/freeword/banks | v3仕様 |
| 支店曖昧検索 | GET | /v3/freeword/banks/{bankCode}/branches | v3仕様 |
| 金融機関種別一覧 | GET | /v3/businessTypes | v3仕様 |
| バージョン取得 | GET | /v3/version | v3仕様 |
よく使うv3リクエスト
金融機関一覧
curl -sS "https://apis.bankcode-jp.com/v3/banks?limit=3&apikey=YOUR_API_KEY" | jq支店情報を取得する
curl -sS "https://apis.bankcode-jp.com/v3/banks/0001/branches/001?apikey=YOUR_API_KEY" | jq日本語を含むfilter検索
curl -sS --get "https://apis.bankcode-jp.com/v3/banks" \
--data-urlencode "filter=hiragana==*みずほ*" \
--data-urlencode "limit=5" \
--data-urlencode "apikey=YOUR_API_KEY" | jq日本語を含むクエリはURLエンコードしてください。curlでは --get と --data-urlencode の利用を推奨します。
共通仕様
バージョン別の完全仕様
- Search API v3 仕様 — 新規実装向けの現行推奨仕様。
- Search API v2 仕様 — v2互換の仕様。
- Search API v1 仕様 — v1互換の仕様。
OpenAPIの位置付け
OpenAPI は、クライアントコード生成、schema確認、自動検証などに使う機械可読仕様です。人間向けの完全な説明は各バージョン仕様ページを参照してください。