API v1 リファレンス

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

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

• オリジン間リソース共有 (Cross-Origin Resource Sharing, CORS)
• クエリパラメータcallbackによるJSONP
• クエリパラメータlimitによる取得件数制御
• クエリパラメータcursorによる次のデータの取得、前のデータの取得
• クエリパラメータfieldsによる部分応答
• クエリパラメータfilterによるフィード用のクリーンでシンプルなフィルタ構文

ベースURL

すべてのAPIはこのURLから始まります。

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

APIキー

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

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

APIキーの取得

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

• ダッシュボードに移動します。(アカウントをお持ちでない場合は アカウントを作成してください。)
• ダッシュボードの「APIキーを作成」ボタンをクリックします。
• 作成されたAPIキーに制限を設定します。(APIキーの盗用、不正使用を防ぐため、HTTPリファラーやIPアドレスで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で１つまたは複数の金融機関リソースを取得することができます。 金融機関リソースには金融機関コード、金融機関名とそのひらがな、カタカナ等が含まれます。

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

{
  "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で金融機関に存在する１つまたは複数の支店リソースを取得することができます。 支店リソースには支店コード、支店名とそのひらがな、カタカナ等が含まれます。

支店リソースのメタデータ

{
  "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: ; または and
• 論理OR: , または or

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

比較

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

プロパティ名

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

演算子

• 等しい : == (パターンマッチングを使用できます。)
• 等しくない : != (パターンマッチングを使用できます。)
• より小さい : =lt= or <
• 以下 : =le= or <=
• より大きい: =gt= or >
• 以上 : =ge= or >=
• 含む : =in=
• 含まない : =out=
• 正規表現 : =re=

引数

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

予約文字や空白を含まない値は引用符で囲むことはできません。
他の引数は一重引用符または二重引用符で囲む必要があります。
例えば引数内で括弧を利用するには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": [
    {
      "code": "0001",
      "name": "みずほ",
      "halfWidthKana": "ﾐｽﾞﾎ",
      "fullWidthKana": "ミズホ",
      "hiragana": "みずほ"
    },
    {
      "code": "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

{
  "code": "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 をリリースしました。