公開API仕様（銀行・支店マスタAPI）

ginconnectが外部提供する銀行・支店マスタ取得APIの仕様。

共通仕様

• ベースURL: https://api.ginconnect.jp
• メソッド: GETのみ
• 文字コード: UTF-8（レスポンスはJSON。sheet系のみ text/plain）
• CORS: 全オリジン許可
• レートリミット: IPごとに15分あたり100リクエスト。超過時は 429 と以下を返す

{
  "success": false,
  "error": { "message": "Too many requests", "retryAfter": 900 }
}

認証

/v1/banks 系はAPIキー認証が必須。APIキーは会員ページから発行する（gk_ プレフィックス）。

• キーが無い・無効・有効期限切れの場合は 401
• 有効なサブスクリプション（active / trialing）が無いユーザーのキーは 402
• キーに許可オリジンが設定されている場合、許可リスト外の Origin ヘッダー付きリクエストは 403（Origin ヘッダーの無いサーバー間通信は制限対象外）

ページング

レスポンスの data.pagination にページング情報が入る:

{ "page": 1, "limit": 100, "total": 1234, "hasMore": true }

• data.count はそのページに含まれる件数、総件数は data.pagination.total。

data_version パラメータ（版指定）

銀行・支店マスタは更新のたびに版（data_version）が発行される。版を指定すると、その時点のマスタ内容を取得できる。過去の照合結果を再現したい場合に使う。

GET /v1/banks?data_version=dv-20260904-1
GET /v1/banks/0001/branches?data_version=latest

• レスポンスの metadata.dataVersion に、実際に使われた版が入る。
• 利用できる版の一覧は /v1/versions で取得できる。ここに出ている版がそのとき指定できる版のすべて。
• 存在しない版・提供を終了した版を指定すると 404 VERSION_NOT_FOUND、形式が不正な場合は 400 INVALID_PARAMETER になる。
• 内容に問題があって版を切り戻した場合、それより新しい版も指定できなくなる（404 VERSION_NOT_FOUND）。一度取得できた版が後から 404 になり得るのはこのケース。そのときは /v1/versions で現在指定できる版を確認する。
• 版を指定しない場合は常に最新版が返る。継続的に最新のデータを使いたい場合は指定不要。

filter パラメータ

絞り込み条件を フィールド:値 形式で指定する。複数条件はカンマ区切り（AND条件）。

GET /v1/banks?filter=code:0001
GET /v1/banks?filter=name:みずほ*,code:00*

対応フィールド:

ワイルドカード:

• ワイルドカードを含まない値は完全一致
• マッチングは大文字小文字を区別しない
• 未対応フィールドや形式不正の条件は無視される（エラーにはならない）

エンドポイント

GET /v1/banks — 金融機関一覧

クエリ: page / limit / filter（上記共通仕様）

レスポンス（200）:

{
  "success": true,
  "data": {
    "banks": [
      {
        "code": "0001",
        "name": "みずほ銀行",
        "katakana": "ミズホギンコウ",
        "hiragana": "みずほぎんこう",
        "halfKatakana": "ﾐｽﾞﾎｷﾞﾝｺｳ"
      }
    ],
    "count": 1,
    "pagination": { "page": 1, "limit": 100, "total": 1, "hasMore": false }
  },
  "metadata": { "timestamp": "2026-07-16T00:00:00.000Z" }
}

GET /v1/banks/{code} — 金融機関詳細

• {code}: 4桁数字の金融機関コード。形式不正は 400 INVALID_PARAMETER、存在しない場合は 404 NOT_FOUND

レスポンス（200）:

{
  "success": true,
  "data": {
    "bank": {
      "code": "0001",
      "name": "みずほ銀行",
      "katakana": "...",
      "hiragana": "...",
      "halfKatakana": "..."
    }
  },
  "metadata": { "timestamp": "2026-07-16T00:00:00.000Z" }
}

GET /v1/banks/{code}/branches — 支店一覧

• {code}: 4桁数字の金融機関コード。形式不正は 400、銀行が存在しない場合は 404
• クエリ: page / limit / filter（code は3桁の支店コード）

レスポンス（200）:

{
  "success": true,
  "data": {
    "branches": [
      {
        "code": "001",
        "name": "東京営業部",
        "katakana": "トウキョウエイギョウブ",
        "hiragana": "とうきょうえいぎょうぶ",
        "halfKatakana": "ﾄｳｷｮｳｴｲｷﾞｮｳﾌﾞ"
      }
    ],
    "count": 1,
    "pagination": { "page": 1, "limit": 100, "total": 1, "hasMore": false }
  },
  "metadata": { "bankCode": "0001", "timestamp": "2026-07-16T00:00:00.000Z" }
}

GET /v1/sheet/bank — Excel / Spreadsheet向け 金融機関単一値取得

セル関数（WEBSERVICE / IMPORTDATA 等）からの利用を想定した、単一値を text/plain で返すAPI。数式のサンプルは Excel / Google Spreadsheet連携 を参照。

• 成功時: 指定フィールドの値を text/plain で返す。フィールドの値が空文字の場合は空文字をそのまま返す（#N/A にはしない）。フィールドが欠落している（undefined / null）場合のみ 200 + #N/A を返す
• 失敗時: ステータス（401 / 402 / 403 / 400 / 404 / 500）に応じて本文は常に #N/A（セル関数でエラー値として扱えるようにするため）
• APIキーに許可オリジンが設定されている場合、許可リスト外の Origin ヘッダー付きリクエストは 403 + #N/A で拒否される（/v1/sheet/banks/{code}/branch も同様）。Origin ヘッダーが付かないリクエスト（curl / Excel / Google Spreadsheet 等のサーバー間・アプリ間通信）は従来どおり利用できる
• 例外: レートリミット超過（429）時はsheet系でも #N/A ではなく共通仕様のJSON形式で返る

GET /v1/sheet/banks/{code}/branch — Excel / Spreadsheet向け 支店単一値取得

• {code}: 金融機関コード
• クエリは /v1/sheet/bank と同じ（code は支店コード、name は支店名の部分一致）

GET /v1/versions — 版一覧

利用できるマスタの版（data_version）を新しい順に返す。ここに出ている版が、そのとき data_version に指定できる版のすべて。

{
  "success": true,
  "data": {
    "latest": "dv-20260904-1",
    "versions": [
      { "version": "dv-20260904-1", "publishedAt": "2026-09-04T00:38:22.000Z", "counts": { "banks": 1146, "branches": 28944 } },
      { "version": "dv-20260828-1", "publishedAt": "2026-08-28T00:53:50.000Z", "counts": { "banks": 1146, "branches": 28931 } }
    ]
  },
  "metadata": { "timestamp": "2026-09-04T01:00:00.000Z" }
}

• latest: data_version を指定しなかったときに使われる版
• counts: その版の収録件数（銀行・支店とも、その版時点の全件）

GET /health — ヘルスチェック

認証不要。{ "success": true, "message": "...", "timestamp": "...", "version": "..." } を返す。

エラーレスポンス

/v1/banks 系のエラーは原則以下の形式:

{ "success": false, "error": { "code": "エラーコード", "message": "説明" } }

※ 認証エラー（401/402/403）は {"error": "メッセージ"} という簡略形式で、他と形が揃っていない。

旧ドキュメント（docs.ginconnect.jp）との差異

旧ドキュメントサイトは旧ginconnectの仕様のまま廃止予定。旧サイトを参照していた利用者向けに、現行仕様との差異をまとめる: