API v3 リファレンス¶

BankcodeJP API は、金融機関・支店の検索を Web / モバイル / サーバーから利用できる API です。

対応している主な機能：

オリジン間リソース共有（CORS）
クエリパラメータ callback による JSONP
limit による取得件数制御
cursor による次/前ページ取得（カーソルベース）
fields による部分応答
filter によるフィルタ構文
sort による並び替え

API一覧¶

ベースURL¶

すべての API はこの URL を起点にします。

https://apis.bankcode-jp.com/

URLエンコード（RFC 3986）

URL のクエリパラメータやパスに含まれる値は UTF-8 でエンコードし、RFC 3986 に準拠したパーセントエンコーディング（URLエンコード）を施してください。
未エンコードの日本語など、RFC 3986 に準拠しない文字列を含むリクエストは HTTP 400 として拒否されます。

APIキー¶

API は API キーで認証します。
認証は クエリパラメータまたは HTTP リクエストヘッダで指定できます。
すべての API リクエストは HTTPS を介して行う必要があります。

認証なしリクエストについて

認証なしの API リクエストを繰り返すと、クライアント IP アドレス、リファラに対してアクセス制限が発生します。

APIキーの取得¶

ダッシュボードに移動します（アカウントがない場合は作成してください）
ダッシュボードの「APIキーを作成」ボタンをクリックします
作成された API キーに制限を設定します（盗用・不正使用防止のため、HTTP リファラーや IP アドレスで保護します）

運用の考え方

BankcodeJP API を利用するプロダクトごとにアカウントが必要です。
同一プロダクト内で API キーを、開発環境用 / 本番環境用 / モバイルアプリ用 / Web アプリ用などに分けて作成できます。

リクエストにAPIキーを設定する¶

API キーはクエリパラメータ / HTTP ヘッダのどちらでも設定できます。
モバイルアプリや IoT デバイス等で IP アドレス/リファラ保護ができない場合は、HTTP ヘッダを推奨します（SSL/TLS により API キーが保護されます）。

クエリパラメータリクエストヘッダ

curl https://apis.bankcode-jp.com/v3/banks -G \
  -d "apikey=..."

curl https://apis.bankcode-jp.com/v3/banks \
  -H "apikey: ..."

レート制限（Rate Limiting）¶

BankcodeJP API にはレート制限があります。
制限を超えたリクエストは拒否され、HTTP ステータスコード 429 Too Many Requests が返されます。
このとき金融機関情報などのレスポンスボディは返却されません。

レート制限の状況は、各リクエストに付与される HTTP レスポンスヘッダーで確認できます。
内容は利用プランにより異なり、必要に応じてプラン変更で緩和できます。

レスポンスヘッダ例¶

x-ratelimit-limit-second: 1
x-ratelimit-limit-day: 350
x-ratelimit-remaining-day: 348
ratelimit-reset: 1

レスポンスヘッダ	説明
`x-ratelimit-limit-second`	1秒間に利用可能な回数の上限
`x-ratelimit-limit-day`	1日あたりの最大リクエスト回数（例：Free プランでは 350 回/日）
`x-ratelimit-remaining-day`	1日あたりの残りリクエスト可能回数
`ratelimit-reset`	レート制限がリセットされるまでの秒数

リソース¶

金融機関リソース¶

API で 1 つまたは複数の金融機関リソースを取得できます。
金融機関リソースには、金融機関コード、金融機関名、ひらがな/カナ等が含まれます。

メタデータ¶

{
  "code": "string",
  "name": "string",
  "halfWidthKana": "string",
  "fullWidthKana": "string",
  "hiragana": "string",
  "businessTypeCode": "string",
  "businessType": "string"
}

プロパティ	値の型	説明	備考
`code`	string	金融機関コード	半角数字4桁
`name`	string	金融機関名
`halfWidthKana`	string	金融機関名（半角カタカナ）	*1
`fullWidthKana`	string	金融機関名（全角カタカナ）	*2
`hiragana`	string	金融機関名（ひらがな）	*3
`businessTypeCode`	string	金融機関種別コード	*4
`businessType`	string	金融機関種別	*4

*1) 半角カタカナと ASCII 印字可能文字のみ含まれます
*2) 全角カタカナと ASCII 印字可能文字の全角文字のみ含まれます
*3) ひらがなと ASCII 印字可能文字の全角文字のみ含まれます
*4) 金融機関種別API で一覧できます

支店リソース¶

API で金融機関に存在する 1 つまたは複数の支店リソースを取得できます。

メタデータ¶

{
  "code": "string",
  "name": "string",
  "halfWidthKana": "string",
  "fullWidthKana": "string",
  "hiragana": "string"
}

プロパティ	値の型	説明	備考
`code`	string	支店コード	半角数字3桁
`name`	string	支店名
`halfWidthKana`	string	支店名（半角カタカナ）	*1
`fullWidthKana`	string	支店名（全角カタカナ）	*2
`hiragana`	string	支店名（ひらがな）	*3

*1) 半角カタカナと ASCII 印字可能文字のみ含まれます
*2) 全角カタカナと ASCII 印字可能文字の全角文字のみ含まれます
*3) ひらがなと ASCII 印字可能文字の全角文字のみ含まれます

金融機関種別リソース¶

金融機関をグルーピングした「種別」のコードと名前を表します。

メタデータ¶

{
  "code": "string",
  "name": "string"
}

プロパティ	値の型	説明
`code`	string	金融機関種別コード
`name`	string	金融機関種別

共通仕様¶

リソースの部分応答¶

部分応答を利用すると、必要な項目のみを取得でき、ペイロードサイズを削減できます。
クエリパラメータ fields に、必要な項目のプロパティ名をカンマ区切りで指定します。

`fields` クエリパラメータによる部分応答リクエスト¶

curl https://apis.bankcode-jp.com/v3/banks \
  -G -v \
  -d "limit=1" \
  -d "fields=code,name,hiragana"

レスポンス例¶

{
  "banks": [
    {
      "code": "0001",
      "name": "みずほ銀行",
      "hiragana": "みずほぎんこう"
    }
  ],
  "size": 1,
  "limit": 1,
  "hasNext": true,
  "nextCursor": "61os1dkE26NnXsq1zcNGbQ",
  "hasPrev": false,
  "version": "2023-05-18T00:02:15+0900"
}

フィルタ構文¶

filter を使用すると、リソースを柔軟にフィルタできます。

例：

/banks?filter=hiragana==あ*
金融機関名ひらがなが「あ」で始まる金融機関を検索します。
/banks/0001/branches?filter=(hiragana==あ*,hiragana==ま*)
金融機関コードが 0001 で、支店名ひらがなが「あ」または「ま」で始まる支店を検索します。

フィルタ式は、論理演算子で関連付けられた 1 つ以上の比較で構成されます。

論理演算子¶

論理 AND: ; または and
論理 OR: , または or

AND 演算子が優先されます（OR より先に評価）。
ただし括弧 ( ) を使うことで評価順序を変更できます。

比較¶

比較は プロパティ名演算子引数 で構成されます。

プロパティ名¶

code や name など、フィルターを適用するフィールドを指定します。

演算子¶

等しい: ==（パターンマッチング利用可）
等しくない: !=（パターンマッチング利用可）
より小さい: =lt= または <
以下: =le= または <=
より大きい: =gt= または >
以上: =ge= または >=
含む: =in=
含まない: =out=
正規表現: =re=

引数¶

引数は、単一の値、またはコンマで区切られた括弧内の複数の値です。
含む / 含まない の引数では、1つまたは複数の引数を括弧で囲みます。

予約文字や空白を含まない値は引用符で囲めません。
その他の引数は一重引用符または二重引用符で囲む必要があります。

例：引数内で括弧を利用する場合
filter=name=re="^.*(葉|田)$"

引用符で囲まれた引数内で一重引用符と二重引用符の両方を使う必要がある場合は、\（バックスラッシュ）でエスケープします。
\ を文字通り使いたい場合は \\ のようにエスケープします。
バックスラッシュは、引用符で囲まれた引数内でのみ特別な意味を持ちます。

パターンマッチング¶

_ は任意の 1 文字と一致
* は 0 文字以上の文字列と一致

正規表現¶

演算子 =re= の引数に一般的な正規表現構文を使用できます。
本 API の正規表現では、^ は行頭、$ は行末を表します。
テキスト先頭/末尾を表したい場合は \A / \z を使用します。

構文詳細：
https://github.com/k-takata/Onigmo/blob/master/doc/RE.ja

文法（EBNF）¶

input          = or, EOF;
or             = and, { ( "," | " or " ) , and };
and            = constraint, { ( ";" | " and " ), constraint };
constraint     = ( group | comparison );
group          = "(", or, ")";

comparison     = selector, comparator, arguments;
selector       = unreserved-str;

comparator     = comp-fiql | comp-alt;
comp-fiql      = ( ( "=", { ALPHA } ) | "!" ), "=";
comp-alt       = ( ">" | "<" ), [ "=" ];

arguments      = ( "(", value, { "," , value }, ")" ) | value;
value          = unreserved-str | double-quoted | single-quoted;

unreserved-str = unreserved, { unreserved }
single-quoted  = "'", { ( escaped | all-chars - ( "'" | "\" ) ) }, "'";
double-quoted  = '"', { ( escaped | all-chars - ( '"' | "\" ) ) }, '"';

reserved       = '"' | "'" | "(" | ")" | ";" | "," | "=" | "!" | "~" | "<" | ">" | " ";
unreserved     = all-chars - reserved;
escaped        = "\", all-chars;
all-chars      = ? all unicode characters ?;

サンプル¶

サンプル	備考
`code==0001`	完全一致
`name==あ*`	前方一致（比較演算子）
`name=re=^あ.*$`	前方一致（正規表現）※単純なパターンマッチングは比較演算子の方が高速です
`code=in=(0001,0002)`	単一プロパティの複数値指定
`code>=0001;code<=0100`	範囲指定
`code==150;(name==出張所,hiragana==おやま)`	AND と OR の組み合わせ

並び替え¶

sort でレスポンス中のリソース出力順を制御できます。
複数指定はカンマ区切り。+ / - で昇順/降順を指定できます。

`sort` クエリパラメータによる並び替えリクエスト¶

curl https://apis.bankcode-jp.com/v3/banks/ \
  -G -v \
  -d "filter=businessTypeCode=in=('00300)" \
  -d "sort=hiragana" \
  -d "limit=5"

レスポンスボディ

{
  "banks": [
    {
      "code": "0040",
      "name": "イオン銀行",
      "halfWidthKana": "ｲｵﾝｷﾞﾝｺｳ",
      "fullWidthKana": "イオンギンコウ",
      "hiragana": "いおんぎんこう",
      "businessTypeCode": "00300",
      "businessType": "新たな形態の銀行"
    },
    {
      "code": "0039",
      "name": "auじぶん銀行",
      "halfWidthKana": "ｴｰﾕｰｼﾞﾌﾞﾝｷﾞﾝｺｳ",
      "fullWidthKana": "エーユージブンギンコウ",
      "hiragana": "えーゆーじぶんぎんこう",
      "businessTypeCode": "00300",
      "businessType": "新たな形態の銀行"
    },
    {
      "code": "0038",
      "name": "住信SBIネット銀行",
      "halfWidthKana": "ｽﾐｼﾝｴｽﾋﾞｰｱｲﾈﾂﾄｷﾞﾝｺｳ",
      "fullWidthKana": "スミシンエスビーアイネツトギンコウ",
      "hiragana": "すみしんえすびーあいねつとぎんこう",
      "businessTypeCode": "00300",
      "businessType": "新たな形態の銀行"
    },
    {
      "code": "0034",
      "name": "セブン銀行",
      "halfWidthKana": "ｾﾌﾞﾝｷﾞﾝｺｳ",
      "fullWidthKana": "セブンギンコウ",
      "hiragana": "せぶんぎんこう",
      "businessTypeCode": "00300",
      "businessType": "新たな形態の銀行"
    },
    {
      "code": "0035",
      "name": "ソニー銀行",
      "halfWidthKana": "ｿﾆｰｷﾞﾝｺｳ",
      "fullWidthKana": "ソニーギンコウ",
      "hiragana": "そにーぎんこう",
      "businessTypeCode": "00300",
      "businessType": "新たな形態の銀行"
    }
  ],
  "size": 5,
  "limit": 5,
  "hasNext": true,
  "nextCursor": "QQqwO9LiIGATQq5vVonU7LtPVaEyp42DYtHkoZyt5TM",
  "hasPrev": false,
  "version": "2023-04-12T07:30:13+0900"
}

API¶

金融機関API¶

金融機関 API は、金融機関の一覧を閲覧したり、金融機関コード/名称等から検索できる API です。

金融機関一覧API¶

GET /v3/banks

クエリパラメータ¶

名前	値	説明
`apiKey`	string	APIキー（クエリ or ヘッダ）
`filter`	string	フィルタ構文
`limit`	integer	取得最大件数（1〜2000、デフォルト 20）
`cursor`	string	フェッチ開始位置（`nextCursor` / `prevCursor`）
`callback`	string	JSONP のコールバック関数名（最大 1000 文字）
`fields`	string	部分応答
`sort`	string	並び替え

レスポンス¶

プロパティ	値の型	説明
`banks`	array	検索された金融機関リソース
`size`	integer	`banks` のサイズ
`limit`	integer	制限された最大件数
`hasNext`	boolean	次のリソースがある場合は `true`
`nextCursor`	string	次のリソースをフェッチするためのカーソル
`hasPrev`	boolean	前のリソースがある場合は `true`
`prevCursor`	string	前のリソースをフェッチするためのカーソル
`version`	string	リソースのバージョン

Note

返されるリソースが 1 つの場合でも banks にはリスト形式で出力されます。

金融機関取得API¶

GET /v3/banks/{code}

パスパラメータ¶

名前	値	説明
`code`	string	金融機関コード

レスポンス¶

レスポンスボディに金融機関リソースが出力されます。

支店API¶

支店 API は、特定の金融機関に所属する支店を検索できる API です。

支店一覧API¶

GET /v3/banks/{bankCode}/branches

パスパラメータ¶

名前	値	説明
`bankCode`	string	金融機関コード

クエリパラメータ¶

名前	値	説明
`apiKey`	string	APIキー（クエリ or ヘッダ）
`filter`	string	フィルタ構文
`limit`	integer	取得最大件数（1〜2000、デフォルト 20）
`cursor`	string	フェッチ開始位置（`nextCursor` / `prevCursor`）
`callback`	string	JSONP のコールバック関数名（最大 1000 文字）
`fields`	string	部分応答
`sort`	string	並び替え

レスポンス¶

レスポンスボディに支店リソースが出力されます。

プロパティ	値の型	説明
bank	object	指定された金融機関リソース
branches	array	検索された支店リソース
size	integer	branchesのサイズ
limit	integer	制限された最大件数
hasNext	string	次のリソースがある場合はtrue
nextCursor	string	次のリソースをフェッチするためのカーソル
hasPrev	string	前のリソースがある場合はtrue
prevCursor	string	前のリソースをフェッチするためのカーソル
version	string	リソースのバージョン

Note

返されるリソースが 1 つの場合でも branches にはリスト形式で出力されます。

支店取得API¶

GET /v3/banks/{bankCode}/branches/{code}

パスパラメータ¶

名前	値	説明
`bankCode`	string	金融機関コード
`code`	string	支店コード

クエリパラメータ¶

名前	値	説明
`apiKey`	string	APIキー（クエリ or ヘッダ）
`callback`	string	JSONP のコールバック関数名（最大 1000 文字）
`fields`	string	部分応答

レスポンス¶

レスポンスボディに支店リソースが出力されます。

プロパティ	値の型	説明	備考
bank	object	指定された金融機関リソース
branch	object	検索された支店リソース

曖昧検索API¶

名称の部分一致で金融機関/支店を検索できます。

名称等の部分一致検索
同音のひらがな/カタカナ（全角/半角）を同一視
小書き文字の同一視
濁点/半濁点の同一視
「ヴァヴィヴヴェヴォ」→「バビブベボ」への正規化

金融機関曖昧検索API¶

GET /v3/freeword/banks

クエリパラメータ¶

名前	値	説明
`apiKey`	string	APIキー（クエリ or ヘッダ）
`freeword`	string	検索文字列
`businessTypeCode`	string[]	金融機関種別コード（複数指定は OR）
`limit`	integer	取得最大件数（1〜2000、デフォルト 20）
`cursor`	string	フェッチ開始位置（`nextCursor` / `prevCursor`）
`callback`	string	JSONP のコールバック関数名（最大 1000 文字）
`fields`	string	部分応答
`sort`	string	並び替え

*1) 金融機関種別API を使うと全ての金融機関種別を一覧できます。

レスポンス¶

レスポンスボディに金融機関リソースが出力されます。

プロパティ	値の型	説明
banks	array	検索された金融機関リソース
size	integer	banksのサイズ
limit	integer	制限された最大件数
hasNext	string	次のリソースがある場合はtrue
nextCursor	string	次のリソースをフェッチするためのカーソル
hasPrev	string	前のリソースがある場合はtrue
prevCursor	string	前のリソースをフェッチするためのカーソル
version	string	リソースのバージョン

Note

返されるリソースが１つの場合でも banks にはリスト形式で出力されます。

支店曖昧検索API¶

GET /v3/freeword/banks/{bankCode}/branches

パスパラメータ¶

名前	値	説明
`bankCode`	string	金融機関コード

クエリパラメータ¶

名前	値	説明
`apiKey`	string	APIキー（クエリ or ヘッダ）
`freeword`	string	検索文字列
`limit`	integer	取得最大件数（1〜2000、デフォルト 20）
`cursor`	string	フェッチ開始位置（`nextCursor` / `prevCursor`）
`callback`	string	JSONP のコールバック関数名（最大 1000 文字）
`fields`	string	部分応答
`sort`	string	並び替え

レスポンス¶

レスポンスボディに支店リソースが出力されます。

プロパティ	値の型	説明
bank	object	指定された金融機関リソース
branches	array	検索された支店リソース
size	integer	branchesのサイズ
limit	integer	制限された最大件数
hasNext	string	次のリソースがある場合はtrue
nextCursor	string	次のリソースをフェッチするためのカーソル
hasPrev	string	前のリソースがある場合はtrue
prevCursor	string	前のリソースをフェッチするためのカーソル
version	string	リソースのバージョン

Note

返されるリソースが１つの場合でも branches にはリスト形式で出力されます。

金融機関種別API¶

金融機関種別の一覧を提供します。

金融機関種別一覧API¶

GET /v3/businessTypes

クエリパラメータ¶

名前	値	説明
`apiKey`	string	APIキー（クエリ or ヘッダ）
`filter`	string	フィルタ構文
`limit`	integer	取得最大件数（1〜2000、デフォルト 2000）
`cursor`	string	フェッチ開始位置（`nextCursor` / `prevCursor`）
`callback`	string	JSONP のコールバック関数名（最大 1000 文字）
`fields`	string	部分応答
`sort`	string	並び替え

レスポンス¶

レスポンスボディに金融機関種別リソースが出力されます。

プロパティ	値の型	説明
businessTypes	array	検索された金融機関リソース
size	integer	businessTypesのサイズ
limit	integer	制限された最大件数
hasNext	string	次のリソースがある場合はtrue
nextCursor	string	次のリソースをフェッチするためのカーソル
hasPrev	string	前のリソースがある場合はtrue
prevCursor	string	前のリソースをフェッチするためのカーソル
version	string	リソースのバージョン

バージョンAPI¶

金融機関データベースのバージョン情報を取得します。

バージョンリソース¶

{
  "version": "string"
}

プロパティ	値の型	説明
`version`	string	金融機関データベースのバージョン

バージョン取得¶

GET /v3/version

クエリパラメータ¶

名前	値	説明
`apiKey`	string	APIキー（クエリ or ヘッダ）

レスポンス¶

レスポンスボディにバージョンリソースが出力されます。

エラーレスポンス¶

HTTP ステータスコードで成功/失敗を示します。

2xx: 成功
4xx: リクエスト不正
5xx: サーバ側エラー

エラーリソース¶

{
  "httpStatusCode": "integer",
  "code": "string",
  "message": "string",
  "validationErrors": [
    {
      "message": "string",
      "paramName": "string",
      "invalidValue": "string"
    }
  ]
}

プロパティ	値の型	説明
httpStatusCode	integer	HTTPステータスコード
code	string	エラーコード
message	string	メッセージ
validationErrors.message	string	エラーメッセージ
validationErrors.paramName	string	エラーとなったパラメータ名
validationErrors.invalidValue	string	エラーとなったパラメータの値

HTTPステータスコード¶

コード	説明
400	Bad Request — リクエストパラメータが不正
401	Unauthorized — APIキーが不正
403	Forbidden — リクエストが許可されていない
404	Not Found — リソースが存在しない
405	Method Not Allowed — HTTPメソッドが不正
406	Not Acceptable — 受付できないリクエスト
429	Too Many Requests — レート制限中
500	Internal Server Error — サーバ異常。後でもう一度実行
503	Service Unavailable — メンテナンス等で一時的にオフライン

リリースノート¶

2023-10-10¶

API仕様変更¶

支店一覧 API / 支店曖昧検索 API のレスポンスに金融機関リソースを追加
data を各リソース英名の複数形へ変更
金融機関一覧 API
支店一覧 API
金融機関曖昧検索 API
支店曖昧検索 API

API v3 リファレンス¶

API一覧¶

金融機関・支店の参照¶

名称からの検索（曖昧検索）¶

マスタ付帯情報¶

共通仕様（全API共通）¶

ベースURL¶

APIキー¶

APIキーの取得¶

リクエストにAPIキーを設定する¶

レート制限（Rate Limiting）¶

レスポンスヘッダ例¶

リソース¶

金融機関リソース¶

メタデータ¶

支店リソース¶

メタデータ¶

金融機関種別リソース¶

メタデータ¶

共通仕様¶

リソースの部分応答¶

fields クエリパラメータによる部分応答リクエスト¶

レスポンス例¶

フィルタ構文¶

論理演算子¶

比較¶

プロパティ名¶

演算子¶

引数¶

パターンマッチング¶

正規表現¶

文法（EBNF）¶

サンプル¶

並び替え¶

sort クエリパラメータによる並び替えリクエスト¶

API¶

金融機関API¶

金融機関一覧API¶

クエリパラメータ¶

レスポンス¶

金融機関取得API¶

パスパラメータ¶

レスポンス¶

支店API¶

支店一覧API¶

パスパラメータ¶

クエリパラメータ¶

レスポンス¶

支店取得API¶

パスパラメータ¶

クエリパラメータ¶

レスポンス¶

曖昧検索API¶

金融機関曖昧検索API¶

クエリパラメータ¶

レスポンス¶

支店曖昧検索API¶

パスパラメータ¶

クエリパラメータ¶

レスポンス¶

金融機関種別API¶

金融機関種別一覧API¶

クエリパラメータ¶

レスポンス¶

バージョンAPI¶

バージョンリソース¶

バージョン取得¶

クエリパラメータ¶

レスポンス¶

エラーレスポンス¶

エラーリソース¶

HTTPステータスコード¶

リリースノート¶

2023-10-10¶

API仕様変更¶

`fields` クエリパラメータによる部分応答リクエスト¶

`sort` クエリパラメータによる並び替えリクエスト¶