NAV Logo
cURL

API v1 リファレンス

BankcodeJP APIでは金融機関をWebクライアントやモバイルアプリケーション、Webサーバーから検索可能なAPIを提供しています。

APIは以下の主要な機能に対応しています。

エンドポイント

APIのベースURLです。

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

APIキー

APIは、APIキーを使用してリクエストを認証します。

認証はリクエストパラメータまたはリクエストヘッダに設定されたAPIキーを介して実行されます。 すべてのAPIリクエストはHTTPSを介して行われる必要があります。

APIキーの取得

以下の手順でAPIキーを取得します。

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

クエリパラメータの場合

# URLの apikey クエリパラメータにAPIキーを設定します。
curl https://apis.bankcode-jp.com/v1/banks \
  -G -v \
  -d "apikey=ここにAPIキーを設定" 

リクエストヘッダの場合

# apikey ヘッダにAPIキーを設定します。
curl https://apis.bankcode-jp.com/v1/banks \
  -G -v \
  -H "apikey: ここにAPIキーを設定" 

APIキーは、URLのクエリパラメータまたは、HTTPヘッダーのどちらかで設定することができます。

インターネットに接続されるモバイルアプリやIoTデバイス等 APIキーをIPアドレスやリファラで保護できない場合、HTTPヘッダーにAPIキーを設定してください。SSL/TLSによりAPIキーが保護されます。

リソース

金融機関リソース

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

金融機関リソースのメタデータ

{
  "code": string,
  "name": string,
  "halfWidthKana": string,
  "fullWidthKana": string,
  "hiragana": string
}
プロパティ 値の型 説明 備考
code string 金融機関コード 半角数字4桁
name string 金融機関名
halfWidthKana string 金融機関名 半角カタカナ *1
fullWidthKana string 金融機関名 全角カタカナ *2
hiragana string 金融機関名 ひらがな *3

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

支店リソース

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印字可能文字の全角文字のみ含まれる。

リソースの部分応答

部分応答を利用すると、APIから返されるリソースに含まれるすべての項目を取得するのではなく必要な項目のみを取得することができます。
返されるデータを選択的にすることにより、ペイロードサイズを削減できます。
リクエストのクエリパラメータfieldsにレスポンスに必要な項目のプロパティ名をカンマ区切りで指定します。

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

# fields クエリパラメータに取得するプロパティ名を指定します。
curl https://apis.bankcode-jp.com/v1/banks \
  -G -v \
  -d "limit=1" \
  -d "fields=code,name,hiragana" 

レスポンスボディ

{
  "data": [
    {
      "code": "0001",
      "name": "みずほ",
      "hiragana": "みずほ"
    }
  ],
  "size": 1,
  "limit": 1,
  "hasNext": true,
  "nextCursor": "61os1dkE26NnXsq1zcNGbQ",
  "hasPrev": false,
  "version": "2020-05-18T00:02:15+0900"
}

フィルタ構文

クエリパラメータのfilterを使用すると、リソースを柔軟にフィルタできます。
例えば、次のようにリソースをクエリできます。

/banks?filter=hiragana==あ*
これは 金融機関名ひらがな が あ で始まる金融機関リソースを検索します。

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

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

論理演算子

AND演算子が優先されます。(OR演算子よりも先に評価されます。)
ただし、括弧( )で囲まれた式を利用して評価の優先順位を変更できます。

比較

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

プロパティ名

プロパティ名は、フィルターを適用するフィールドたとえばcodenameなどを識別します。

演算子

引数

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

予約文字や空白を含まない値は引用符で囲むことはできません。
他の引数は一重引用符または二重引用符で囲む必要があります。
例えば引数内で括弧を利用するにはfilter=name=re="^.*(葉|田)$"のように引用符で囲みます。

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

パターンマッチング

演算子の等しい等しくないの引数では、パターンマッチングを使用できます。

引数の中にあるアンダースコア _ はすべての一文字との一致を意味し、アスタリスク * は 0 文字以上の文字列との一致を意味します。

正規表現

演算子正規表現の引数に、一般的な正規表現構文を使用できます。

APIの正規表現エンジンの構文は他の多くの正規表現エンジンの構文と同じですが、一部特徴的な違いがあります。

他の正規表現の構文との特徴的な違いは ^$ です。APIの正規表現の構文では ^ は行頭を表し、 $ は行末を表します。
他の多くの正規表現の構文では、 ^ はテキストの先頭を表し、 $ はテキストの最後を表します。
APIの正規表現の構文ではテキストの先頭を表す場合は \A を使い、テキストの最後を表す場合は \z を使います。

すべての構文は以下で説明されています。
https://github.com/k-takata/Onigmo/blob/master/doc/RE.ja

フィルタ構文の文法

 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の組み合わせ

金融機関API

金融機関APIは、日本の金融機関の一覧を閲覧したり、金融機関コード、金融機関名などから検索できるAPIです。 金融機関APIを利用すれば、金融機関を検索する機能をカスタムWebサイト、Webサーバやモバイルアプリケーションへシンプルに統合できます。

金融機関一覧API

GET /v1/banks

$ curl https://apis.bankcode-jp.com/v1/banks \
  -G -v \
  -d "limit=2"

RESPONSE

{
  "data": [
    {
      "bankCode": "0001",
      "name": "みずほ",
      "halfWidthKana": "ミズホ",
      "fullWidthKana": "ミズホ",
      "hiragana": "みずほ"
    },
    {
      "bankCode": "0041",
      "name": "大和ネクスト",
      "halfWidthKana": "ダイワネクスト",
      "fullWidthKana": "ダイワネクスト",
      "hiragana": "だいわねくすと"
    }
  ],
  "size": 2,
  "limit": 2,
  "hasNext": true,
  "nextCursor": "znouHjPHtks9bxsjlZKcewCrM",
  "hasPrev": false,
  "version": "2020-05-19T00:04:31+0900"
}

金融機関名の完全一致や前方一致で金融機関リソースを検索します。

クエリパラメータでその挙動をカスタマイズできます。パラメータが指定されていない場合はパラメータ固有のデフォルトの挙動になります。

リクエスト

GET https://apis.bankcode-jp.com/v1/banks

クエリパラメータ

名前 説明
apiKey string APIキーをこのクエリパラメータもしくは、HTTPリクエスト ヘッダーのどちらかに設定します。
filter string リソースを検索するフィルタ構文
limit integer 取得する最大件数。1~2000。(デフォルト: 20)
cursor string フェッチを開始する位置を示すカーソル (直前のレスポンスのnextCursorまたはprevCursorの値)
callback string JSONPを利用する場合のコールバック関数名。最大1000文字。
fields string レスポンスに含める項目。リソースの部分応答を参照。

レスポンス

レスポンスボディに金融機関リソースが出力されます。 callbackクエリパラメータを指定した場合はcallbackの引数としてリソースが出力されます。 APIを正常に実行できない場合は エラー が出力されます。

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

金融機関取得API

GET /v1/banks/{code}

$ curl https://apis.bankcode-jp.com/v1/banks/0001 

RESPONSE

{
  "bankCode": "0001",
  "name": "みずほ",
  "halfWidthKana": "ミズホ",
  "fullWidthKana": "ミズホ",
  "hiragana": "みずほ"
}

金融機関リソースを取得します。

リクエスト

GET https://apis.bankcode-jp.com/v1/banks/{code}

パスパラメータ

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

クエリパラメータ

名前 説明
apiKey string APIキーをこのクエリパラメータもしくは、HTTPリクエスト ヘッダーのどちらかに設定します。
callback string JSONPを利用する場合のコールバック関数名。最大1000文字。
fields string レスポンスに含める項目。リソースの部分応答を参照。

レスポンス

レスポンスボディに金融機関リソースが出力されます。 callbackクエリパラメータを指定した場合はcallbackの引数としてリソースが出力されます。 APIを正常に実行できない場合は エラー が出力されます。

支店API

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

支店一覧API

GET /v1/banks/{bankCode}/branches

$ curl https://apis.bankcode-jp.com/v1/banks/0001/branches \
  -G -v \
  -d "limit=2"

RESPONSE

{
  "data": [
    {
      "code": "001",
      "name": "東京営業部",
      "halfWidthKana": "トウキヨウ",
      "fullWidthKana": "トウキヨウ",
      "hiragana": "とうきよう"
    },
    {
      "code": "001",
      "name": "東京都庁公営企業出張所",
      "halfWidthKana": "トウキヨウトチヨウコウエイ",
      "fullWidthKana": "トウキヨウトチヨウコウエイ",
      "hiragana": "とうきようとちようこうえい"
    }
  ],
  "size": 2,
  "limit": 2,
  "hasNext": true,
  "nextCursor": "4rCSfn5SF3UWXT49nbK-Ll8C6Cb35b2ncW--Fp9vxL8",
  "hasPrev": false,
  "version": "2020-08-02T18:34:46+0900"
}

特定の金融機関に所蔵する支店リソースを検索します。

クエリパラメータでその挙動をカスタマイズできます。パラメータが指定されていない場合はパラメータ固有のデフォルトの挙動になります。

リクエスト

GET https://apis.bankcode-jp.com/v1/banks/{bankCode}/branches

クエリパラメータ

名前 説明
apiKey string APIキーをこのクエリパラメータもしくは、HTTPリクエスト ヘッダーのどちらかに設定します。
filter string リソースを検索するフィルタ構文
limit integer 取得する最大件数。1~2000。(デフォルト: 20)
cursor string フェッチを開始する位置を示すカーソル (直前のレスポンスのnextCursorまたはprevCursorの値)
callback string JSONPを利用する場合のコールバック関数名。最大1000文字。
fields string レスポンスに含める項目。リソースの部分応答を参照。

レスポンス

レスポンスボディに支店リソースが出力されます。 callbackクエリパラメータを指定した場合はcallbackの引数としてリソースが出力されます。 APIを正常に実行できない場合は エラー が出力されます。

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

支店取得API

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

$ curl https://apis.bankcode-jp.com/v1/banks/0001/branches/001

RESPONSE

[
  {
    "code": "001",
    "name": "東京営業部",
    "halfWidthKana": "トウキヨウ",
    "fullWidthKana": "トウキヨウ",
    "hiragana": "とうきよう"
  },
  {
    "code": "001",
    "name": "東京都庁公営企業出張所",
    "halfWidthKana": "トウキヨウトチヨウコウエイ",
    "fullWidthKana": "トウキヨウトチヨウコウエイ",
    "hiragana": "とうきようとちようこうえい"
  }
]

支店リソースを取得します。

リクエスト

GET https://apis.bankcode-jp.com/v1/banks/{bankCode}/branches/{code}

パスパラメータ

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

クエリパラメータ

名前 説明
apiKey string APIキーをこのクエリパラメータもしくは、HTTPリクエスト ヘッダーのどちらかに設定します。
callback string JSONPを利用する場合のコールバック関数名。最大1000文字。
fields string レスポンスに含める項目。リソースの部分応答を参照。

レスポンス

レスポンスボディに支店リソースが出力されます。 callbackクエリパラメータを指定した場合はcallbackの引数としてリソースが出力されます。 APIを正常に実行できない場合は エラー が出力されます。

バージョンAPI

取り扱っている金融機関データベースのバージョン情報を取得するAPIです。

バージョンリソース

バージョンリソースのメタデータ

{
  "version": string
}
プロパティ 値の型 説明 備考
version string 金融機関データベースのバージョン

バージョン取得

GET /v1/version

$ curl https://apis.bankcode-jp.com/v1/version \
  -G -v 

RESPONSE

{
  "version": "2020-08-02T18:34:46+0900"
}

リクエスト

GET https://apis.bankcode-jp.com/v1/version

クエリパラメータ

名前 説明
apiKey string APIキーをこのクエリパラメータもしくは、HTTPリクエスト ヘッダーのどちらかに設定します。

レスポンス

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

エラーレスポンス

BankcodeJP APIは、HTTPレスポンスコードを使ってAPIリクエストの成功または失敗を示します。2xxの範囲のコードは成功を示します。

APIを正常に実行できない場合、HTTPステータスコードが 2xx以外で レスポンスボディにはデバッグ目的でのみ利用可能なエラーリソースが出力されます。 APIによってハンドリングできない致命的なエラーが発生した場合 HTTPステータスコードは 5xxで返却されますが、エラーリソースが出力される保証はありません。

4xxの範囲のコードは不正なリクエストパラメータにより失敗したエラーであることを示しています。

5xxの範囲のコードは、BankcodeJP APIのサーバにエラーがあることを示しています。

リソース

エラーのメタデータ

{
  "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 -- メンテナンスのため一時的にオフラインです。後でもう一度やり直してください。

リリースノート

2020-9-10

API v1 をリリースしました。
(v1より古いAPIドキュメントは公開されていません。)