【銀行くんAPI】金融機関APIを使って銀行名・支店名を取得する方法

読みたい箇所へ移動する

はじめに

ウェブアプリケーションやシステム開発において、ユーザーから金融機関コードや支店コードを入力してもらい、それに対応する銀行名や支店名を表示する機能は非常に有用です。しかし、全国の銀行や支店情報を手動で管理するのは現実的ではありません。そこで今回は、金融機関API銀行くんAPI」を利用して、金融機関コードと支店コードから銀行名および支店名を取得する方法をご紹介します。

銀行くんAPIとは

銀行、信用金庫等の金融機関コードを検索できるAPIを無料で提供しています。個人利用、商用利用ともにリクエスト数に制限はなく無料です。

銀行くん | 金融機関コード API (teraren.com)

処理の流れ

  1. ユーザー入力の取得:金融機関コードと支店コードをユーザーから入力してもらいます。
  2. 入力値の検証とパディング:コードが所定の桁数になるようにゼロパディングを行います。
  3. APIリクエストの送信:銀行名と支店名を取得するために、銀行くんAPIにリクエストを送信します。
  4. 結果の表示:取得した銀行名と支店名をユーザーに表示します。
  5. エラーハンドリング:エラーが発生した場合、適切なメッセージをユーザーに伝えます。

完成コード

以下に、JavaScriptで実装したコードを示します。

/**
 * 金融機関名・支店名を取得し表示
 */
document.addEventListener('DOMContentLoaded', () => {
  document
    .querySelector('.js_searchBtn')
    .addEventListener('click', async () => {
      const bankInput = document.querySelector('.js_bankNumber').value;
      const branchInput = document.querySelector('.js_branchNumber').value;

      // 金融機関コードが入力されていない場合のエラーメッセージ
      if (!bankInput) {
        alert('金融機関コードを入力してください');
        return;
      }
      // 支店コードが入力されていない場合のエラーメッセージ
      if (!branchInput) {
        alert('支店コードを入力してください');
        return;
      }

      // 金融機関コードと支店コードを必要な桁数にパディング
      const bankNumber = bankInput.padStart(4, '0');
      const branchNumber = branchInput.padStart(3, '0');

      try {
        // 金融機関名を取得するためのAPIリクエスト
        const bankResponse = await fetchBankData(bankNumber);
        const bankName = bankResponse.normalize.name;

        // 支店名を取得するためのAPIリクエスト
        const branchResponse = await fetchAllBranches(bankNumber);
        const branchName = findBranchName(branchResponse, branchNumber);

        // 結果を表示する
        displayResults(bankName, branchName);
      } catch (error) {
        handleError(error);
      }
    });

  // 金融機関コードを使って金融機関名を取得する非同期関数
  async function fetchBankData(bankNumber) {
    const apiEndpoint = `https://bank.teraren.com/banks/${bankNumber}.json`;
    try {
      const response = await fetch(apiEndpoint);
      if (!response.ok) {
        throw new Error(
          '金融機関データを取得できませんでした。再試行してください。'
        );
      }
      const data = await response.json();
      if (data.error) {
        throw new Error(
          '指定された金融機関が見つかりません。番号を確認してください。'
        );
      }
      return data;
    } catch (error) {
      throw new Error(
        '指定された金融機関が見つかりません。番号を確認してください。'
      );
    }
  }

  // 金融機関コードを使って支店名リストを取得する非同期関数
  async function fetchAllBranches(bankNumber) {
    let allBranches = [];
    let currentPage = 1;
    let hasMore = true; // 追加のページが存在するかを示すフラグ
    const MAX_PAGES = 30; // 最大ページ数を設定

    while (hasMore && currentPage <= MAX_PAGES) {
      try {
        const response = await fetch(
          `https://bank.teraren.com/banks/${bankNumber}/branches.json?page=${currentPage}`
        );
        if (!response.ok) {
          throw new Error(
            '支店データを取得できませんでした。再試行してください。'
          );
        }
        const data = await response.json();
        if (data && data.length > 0) {
          // データが存在する場合、全支店リストに追加し、ページ番号を増加
          allBranches = allBranches.concat(data);
          currentPage++;
        } else {
          // データが存在しない場合、追加のページはないと判断
          hasMore = false;
        }
      } catch (error) {
        throw new Error('再試行してください。');
      }
    }
    return allBranches;
  }

  // 支店データリストから支店コードに一致する支店名を検索する関数
  function findBranchName(branchData, branchNumber) {
    const branchInfo = branchData.find(
      (branch) => branch.code === branchNumber
    );
    if (!branchInfo) {
      alert('指定された支店が見つかりません。支店コードを確認してください。');
      return '';
    }
    return branchInfo.name;
  }

  // 金融機関名と支店名を画面に表示する関数
  function displayResults(bankName, branchName) {
    document.querySelector('.js_bankName').value = bankName;
    document.querySelector('.js_branchName').value = branchName;
  }

  // エラーメッセージ表示。ログを記録する関数
  function handleError(error) {
    console.error('エラー:', error);
    alert(`エラーが発生しました: ${error.message}`);
  }
});

コードの解説

ユーザー入力の取得と検証

const bankInput = document.querySelector('.js_bankNumber').value;
const branchInput = document.querySelector('.js_branchNumber').value;

if (!bankInput) {
  alert('金融機関コードを入力してください');
  return;
}
if (!branchInput) {
  alert('支店コードを入力してください');
  return;
}
  • ユーザーが入力した金融機関コードと支店コードを取得します。
  • 入力がない場合は、アラートでエラーメッセージを表示し、処理を中断します。

コードのゼロパディング

const bankNumber = bankInput.padStart(4, '0');
const branchNumber = branchInput.padStart(3, '0');
  • 金融機関コードは4桁、支店コードは3桁である必要があるため、足りない桁数をゼロで埋めます

金融機関名の取得

const branchResponse = await fetchAllBranches(bankNumber);
const branchName = findBranchName(branchResponse, branchNumber);
  • fetchBankData関数を呼び出して、金融機関コードに対応する銀行のデータを取得します。
  • 正常化された銀行名を取得するために、normalize.nameを使用します。

支店名の取得

const branchResponse = await fetchAllBranches(bankNumber);
const branchName = findBranchName(branchResponse, branchNumber);
  • fetchAllBranches関数を使って、指定された金融機関の全支店リストを取得します。
  • findBranchName関数で、支店コードに一致する支店名を検索します。

結果の表示

displayResults(bankName, branchName);
  • 取得した銀行名と支店名を画面上の指定された要素に表示します

エラーハンドリング

function handleError(error) {
  console.error('エラー:', error);
  alert(`エラーが発生しました: ${error.message}`);
}
  • エラーが発生した場合は、コンソールにエラーログを記録し、ユーザーにアラートで通知します。

APIリクエスト

金融機関データの取得

async function fetchBankData(bankNumber) {
  const apiEndpoint = `https://bank.teraren.com/banks/${bankNumber}.json`;
  // 以下略
}
  • 指定した金融機関コードを用いて、銀行くんAPIから銀行の情報を取得します。

支店データの取得

async function fetchAllBranches(bankNumber) {
  // 以下略
}
  • ページネーションを考慮して、全ての支店データを取得します。
  • hasMoreフラグとcurrentPageを使って、データがなくなるまでループします。

入力フォームのHTML例

<input type="text" class="js_bankNumber" placeholder="金融機関コード">
<input type="text" class="js_branchNumber" placeholder="支店コード">
<button class="js_searchBtn">検索</button>
<input type="text" class="js_bankName" placeholder="銀行名" readonly>
<input type="text" class="js_branchName" placeholder="支店名" readonly>
  • ユーザーがコードを入力し、検索ボタンをクリックすると、銀行名と支店名が表示されます。

まとめ

金融機関APIである「銀行くんAPI」を活用することで、金融機関コードと支店コードから対応する銀行名と支店名を簡単に取得できます。APIを利用することで、データの更新や管理の手間を省くことができ、ユーザーにとっても利便性の高い機能を提供できます。ぜひ、自身のプロジェクトに取り入れてみてください。


参考記事

金融機関コード API仕様書

Reactで金融機関検索APIをたたいてみた (zenn.dev)

手助けが必要なお客様へ

NaraWebではWebサイトの新規制作やサイトリニューアル、ちょっとした改修・カスタマイズを行っております。
ご興味をお持ちになりましたら、まずはお気軽にご相談ください。

読みたい箇所へ移動する