Search API v2 → v3 マイグレーション¶
本ページは、BankcodeJP Search API（検索系 API） を
v2 から v3 へ移行する際の変更点をまとめたガイドです。
v3 は API の整理・命名統一・レスポンス構造の明確化が主目的であり、
検索ロジックそのもの（曖昧検索の挙動等）は v2 から変更されていません。
0. 先に結論¶
- ベースURLが
/v2/→/v3/に変更 - レスポンスのトップレベルキーが変更（
data→ リソース名） - 支店一覧 / 支店曖昧検索 API のレスポンスに
bankが追加 - 検索条件・フィルタ構文・並び替え仕様は 互換
1. ベースURLの変更¶
| v2 | v3 | |
|---|---|---|
| base URL | https://apis.bankcode-jp.com/v2/ |
https://apis.bankcode-jp.com/ |
例¶
- https://apis.bankcode-jp.com/v2/banks
+ https://apis.bankcode-jp.com/v3/banks
2. エンドポイント対応表¶
金融機関・支店 API¶
| 機能 | v2 | v3 |
|---|---|---|
| 金融機関一覧 | /v2/banks |
/v3/banks |
| 金融機関取得 | /v2/banks/{code} |
/v3/banks/{code} |
| 支店一覧 | /v2/banks/{bankCode}/branches |
/v3/banks/{bankCode}/branches |
| 支店取得 | /v2/banks/{bankCode}/branches/{code} |
/v3/banks/{bankCode}/branches/{code} |
曖昧検索 API¶
| 機能 | v2 | v3 |
|---|---|---|
| 金融機関曖昧検索 | /v2/freeword/banks |
/v3/freeword/banks |
| 支店曖昧検索 | /v2/freeword/banks/{bankCode}/branches |
/v3/freeword/banks/{bankCode}/branches |
3. レスポンス構造の変更（重要）¶
3.1 一覧系レスポンスのトップレベルキー¶
v2 では すべて data 固定でしたが、
v3 では リソース名に応じたキー名に変更されています。
| API | v2 | v3 |
|---|---|---|
| 金融機関一覧 | data |
banks |
| 支店一覧 | data |
branches |
| 金融機関曖昧検索 | data |
banks |
| 支店曖昧検索 | data |
branches |
| 金融機関種別一覧 | data |
businessTypes |
例：金融機関一覧¶
v2¶
{
"data": [ { ... } ],
"size": 3,
"limit": 3,
"hasNext": true
}
v3¶
{
"banks": [ { ... } ],
"size": 3,
"limit": 3,
"hasNext": true
}
⚠ フロントエンドで data に直接依存している場合は修正必須
4. 支店 API のレスポンス拡張¶
4.1 支店一覧 / 支店曖昧検索 API¶
v3 では、以下の API のレスポンスに 金融機関リソース (bank) が追加されました。
- 支店一覧 API
- 支店曖昧検索 API
v2（支店一覧）¶
{
"data": [ { ...branch } ]
}
v3（支店一覧）¶
{
"bank": { ...bank },
"branches": [ { ...branch } ]
}
これにより、 - 支店データ表示時に 別途銀行APIを叩く必要がなくなります - 既存実装では 未使用フィールドとして無視して問題ありません
5. クエリパラメータ互換性¶
以下のクエリパラメータは v2 → v3 で完全互換です。
filterlimitcursorfieldssortcallbackapiKey（クエリ / ヘッダ）
移行時に書き換えは不要です。
6. フィルタ構文・並び替え¶
- フィルタ構文（FIQL 互換）は v2 と同一
sortの指定方法・挙動も変更なし
/v3/banks?filter=hiragana==あ*&sort=hiragana
7. エラーレスポンス¶
- HTTP ステータスコード体系は v2 と同一
- エラーレスポンスの JSON 構造も変更なし
8. 最小移行例¶
v2¶
curl https://apis.bankcode-jp.com/v2/freeword/banks \
-G -d "freeword=ちゅうおう"
v3¶
curl https://apis.bankcode-jp.com/v3/freeword/banks \
-G -d "freeword=ちゅうおう"
レスポンスの トップレベルキーのみ変更されます。
9. 移行チェックリスト¶
- [ ]
/v2/→/v3/に URL を変更 - [ ] レスポンスの
data参照を修正 - [ ] 支店 API で
bankが追加されていることを確認 - [ ] フィルタ・sort・cursor 周りはそのままで OK
補足¶
v3 は Search API の破壊的変更を最小限に抑えた整理版です。
検索精度・曖昧検索の正規化ロジックは v2 から変更されていません。