Common Search API Specification

Search API 共通仕様

Search APIのリソース、部分応答、フィルタ、並び替え、カーソルページングの共通仕様です。

リソース

リソース	主な項目
金融機関	`code`, `name`, `halfWidthKana`, `fullWidthKana`, `hiragana`, `businessTypeCode`, `businessType`
支店	`code`, `name`, `halfWidthKana`, `fullWidthKana`, `hiragana`
金融機関種別	`code`, `name`

全フィールドの型定義は OpenAPI仕様を参照してください。

リソースの部分応答: fields

fields を指定すると、返却されるリソース項目を必要な項目だけに絞れます。ペイロードサイズ削減に有効です。

curl -sS --get "https://apis.bankcode-jp.com/v3/banks" \
  --data-urlencode "fields=code,name,hiragana" \
  --data-urlencode "limit=3" \
  --data-urlencode "apikey=YOUR_API_KEY"

{
  "banks": [
    { "code": "0001", "name": "みずほ銀行", "hiragana": "みずほ" }
  ],
  "size": 3,
  "limit": 3,
  "hasNext": true,
  "nextCursor": "...",
  "hasPrev": false,
  "version": "2026-05-11T08:14:30+0900"
}

v3の一覧レスポンスでは、fields は配列内のリソース項目に適用されます。size、limit、hasNext、version などのメタ項目はレスポンスに含まれます。

filter の基本

通常利用で最もよく使うのは、完全一致と部分一致です。日本語を含む場合は必ずURLエンコードしてください。

完全一致

curl -sS --get "https://apis.bankcode-jp.com/v3/banks"   --data-urlencode "filter=hiragana==みずほ"   --data-urlencode "apikey=YOUR_API_KEY"

部分一致

curl -sS --get "https://apis.bankcode-jp.com/v3/banks"   --data-urlencode "filter=hiragana==*みずほ*"   --data-urlencode "apikey=YOUR_API_KEY"

フィルタ構文: filter

filter を使用すると、リソースを柔軟に絞り込めます。日本語などの非ASCII文字を含む場合は、必ずURLエンコードしてください。curlでは --get と --data-urlencode を推奨します。

curl -sS --get "https://apis.bankcode-jp.com/v3/banks" \
  --data-urlencode "filter=name==みずほ銀行" \
  --data-urlencode "limit=5" \
  --data-urlencode "apikey=YOUR_API_KEY"

比較演算子

演算子	意味	例
`==`	等しい。`*` / `_` によるパターンマッチング可	`hiragana==みずほ`
`!=`	等しくない。パターンマッチング可	`code!=0001`
`=lt=`	より小さい	`code=lt=0100`
`=le=`	以下	`code=le=0100`
`=gt=`	より大きい	`code=gt=0001`
`=ge=`	以上	`code=ge=0001`
`=in=`	指定リストに含まれる	`businessTypeCode=in=(00200,00700)`
`=out=`	指定リストに含まれない	`code=out=(0001,0005)`
`=re=`	正規表現に一致	`name=re="^.*銀行$"`

パターンマッチング

記号	意味	例
`*`	0文字以上の任意文字	`hiragana==みずほ`
`_`	任意の1文字	`code==00_1`

論理演算

複数条件は論理演算子で関連付けできます。括弧でグルーピングできます。

# OR条件の例
filter=(hiragana==あ*,hiragana==ま*)

# AND条件の例
filter=businessTypeCode==00200;hiragana==*みずほ*

例

# 完全一致
filter=hiragana==みずほ

# 部分一致
filter=hiragana==*みずほ*

# 支店名ひらがなの部分一致
filter=hiragana==*とうきよう*

並び替え: sort

sort でレスポンスに含まれるリソースの出力順序を指定できます。複数項目の場合はカンマ区切りです。

curl -sS --get "https://apis.bankcode-jp.com/v3/banks" \
  --data-urlencode "sort=code" \
  --data-urlencode "limit=5" \
  --data-urlencode "apikey=YOUR_API_KEY"

指定	意味
`sort=code`	`code` 昇順
`sort=-code`	`code` 降順
`sort=businessTypeCode,code`	`businessTypeCode` 昇順、次に `code` 昇順

カーソルページング

一覧系APIは limit とカーソルでページングします。レスポンスには hasNext、nextCursor、hasPrev が含まれます。

# 1ページ目
curl "https://apis.bankcode-jp.com/v3/banks?limit=100&apikey=YOUR_API_KEY"

# 次ページ
curl "https://apis.bankcode-jp.com/v3/banks?limit=100&cursor=NEXT_CURSOR&apikey=YOUR_API_KEY"

URLエンコード

日本語を含むクエリ文字列をURLに直書きすると、ロードバランサやプロキシで 400 Bad Request になる場合があります。

curlでは以下の形式を使ってください。

curl -sS --get "https://apis.bankcode-jp.com/v3/banks" \
  --data-urlencode "filter=name==みずほ銀行" \
  --data-urlencode "limit=5" \
  --data-urlencode "apikey=YOUR_API_KEY"