Search API v1 → v2 マイグレーション

本ページは BankcodeJP の Search API（検索系） を、
v1 から v2 に移行する際の差分をまとめたものです。

結論：
- ほとんどの呼び出しは URL の /v1/ → /v2/ 置換で動きます
- v2 で 並び替え（sort） と 金融機関種別（businessType*） が追加されました
- v2 以降、（後発で）曖昧検索（freeword） が v2 に追加されています（v1 には存在しません）

---

1. ベースURL

	v1	v2
base	https://apis.bankcode-jp.com/v1/	https://apis.bankcode-jp.com/v2/

---

2. エンドポイント対応表

2.1 金融機関（banks）

機能	v1	v2
一覧/検索	GET /v1/banks	GET /v2/banks
取得	GET /v1/banks/{code}	GET /v2/banks/{code}

2.2 支店（branches）

機能	v1	v2
一覧/検索	GET /v1/banks/{bankCode}/branches	GET /v2/banks/{bankCode}/branches
取得	GET /v1/banks/{bankCode}/branches/{code}	GET /v2/banks/{bankCode}/branches/{code}

2.3 v2 で追加された Search API（曖昧検索）

v1 には 曖昧検索 API は存在しません。
v2 で以下が追加されています（2023-01-05 リリース）。

機能	v2
金融機関曖昧検索	GET /v2/freeword/banks
支店曖昧検索	GET /v2/freeword/banks/{bankCode}/branches

---

3. クエリパラメータ差分

v1/v2 とも、以下の「共通パラメータ」は基本的に同一です：

• callback（JSONP）
• limit（件数）
• cursor（カーソルページング）
• fields（部分応答）
• filter（フィルタ構文）
• apiKey（クエリまたはヘッダ）

v2 で追加されたパラメータ（重要）

sort

v2 では banks / branches の一覧APIに sort が追加されました。

• sort=hiragana（昇順）
• sort=-hiragana（降順）
• sort=hiragana,code（複合キー）

---

4. レスポンス形式

一覧系レスポンス（v1/v2 共通）

一覧系（/banks、/branches、/freeword/*）は、v1/v2 とも以下の形式です。

{
  "data": [ ... ],
  "size": 3,
  "limit": 3,
  "hasNext": true,
  "nextCursor": "...",
  "hasPrev": false,
  "prevCursor": "...",
  "version": "..."
}

移行で 構造が変わる前提にはしなくてOK です。

単体取得レスポンス（注意）

• GET /banks/{code} は 単一オブジェクト を返します（v1/v2 共通）
• GET /banks/{bankCode}/branches/{code} は、仕様上 配列が返る例があります（v1/v2 共通）

この挙動に依存している実装がある場合、移行後もそのまま維持されます。

---

5. リソース差分

5.1 金融機関リソース（banks）

v2 では、金融機関リソースに以下が追加されました：

• businessTypeCode
• businessType

既存の code / name / halfWidthKana / fullWidthKana / hiragana はそのままです。

5.2 支店リソース（branches）

支店リソースは v1/v2 で実質差分なしです。

---

6. 具体例（最小移行）

v1

curl "https://apis.bankcode-jp.com/v1/banks?limit=3" -H "apikey: YOUR_KEY"

v2

curl "https://apis.bankcode-jp.com/v2/banks?limit=3" -H "apikey: YOUR_KEY"

v2（並び替えを使う）

curl "https://apis.bankcode-jp.com/v2/banks?limit=5&sort=hiragana" -H "apikey: YOUR_KEY"

---

7. 移行チェックリスト

• [ ] base URL を /v1/ → /v2/ に変更
• [ ] （必要なら）sort を追加して表示順を安定化
• [ ] banks の戻り値で businessType* を参照する場合は v2 で利用可
• [ ] v1 には freeword が無いので、曖昧検索が必要なら v2 の /freeword/* に切替

---