【jQuery】jquery.jpostal.jsで郵便番号から住所を自動補完する完全ガイド｜分割表示・バリデーション・エラー処理まで

ECサイトや会員登録フォームで「郵便番号を入力すると住所が自動補完される」機能は、ユーザーの入力負荷を大幅に減らし離脱率の低下に繋がります。jquery.jpostal.js を使えば、jQueryプロジェクトに数行で郵便番号→住所の自動補完機能を追加できます。

jquery.jpostal.jsとは

jquery.jpostal.jsは、郵便番号データベースAPIに問い合わせて住所情報を取得するjQueryプラグインです。フォームの入力フィールドにバインドするだけで郵便番号→住所の自動補完を実装できます。

導入方法

CDNから読み込む

GitHubからCDN経由で読み込む方法が最も手軽です。

<!-- 1. jQueryを先に読み込む -->
<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>

<!-- 2. jquery.jpostal.jsを読み込む -->
<script src="https://cdn.jsdelivr.net/npm/jquery.jpostal.js@1.0.1/jquery.jpostal.min.js"></script>

ローカルファイルを使う場合

GitHubのリポジトリ（harisenbon/jpostal）から jquery.jpostal.js をダウンロードし、プロジェクトの適切なディレクトリに配置してパスを指定してください。

基本の使い方：住所を1つのフィールドに補完する

最もシンプルなパターンです。郵便番号入力欄を離れると（focusout）、住所フィールドに都道府県から町域までの住所が自動で入力されます。

<form>
  <div>
    <label>郵便番号（ハイフンなし7桁またはハイフンあり）</label>
    <input type="text" id="postal-code" placeholder="1234567">
  </div>
  <div>
    <label>住所</label>
    <input type="text" id="address" placeholder="自動補完されます">
  </div>
</form>

$(function () {
  $('#postal-code').jpostal({
    postcode: ['#postal-code'],  // 郵便番号の入力フィールド
    address: {
      '#address': '%3%4%5%6%7'   // 住所を補完するフィールドとフォーマット
    }
  });
});

都道府県・市区町村・町域を別フィールドに分割する

実務のフォームでは都道府県・市区町村・町域をそれぞれ別の入力欄に分けるケースが多いです。address オブジェクトに複数のフィールドを定義することで実現できます。

<label>郵便番号</label>
<input type="text" id="zip" placeholder="123-4567">

<label>都道府県</label>
<input type="text" id="pref" placeholder="東京都">

<label>市区町村</label>
<input type="text" id="city" placeholder="新宿区">

<label>町域</label>
<input type="text" id="town" placeholder="西新宿">

<label>番地・建物名（手動入力）</label>
<input type="text" id="building" placeholder="2-8-1">

$(function () {
  $('#zip').jpostal({
    postcode: ['#zip'],
    address: {
      '#pref': '%3',    // 都道府県のみ
      '#city': '%4',    // 市区町村のみ
      '#town': '%5%6%7' // 町域・丁目・番地
    }
  });
});

フォーマットコード一覧

jpostal.jsで使えるフォーマットコードは以下の通りです。これらを組み合わせて address の値に設定します。

ハイフンあり・なし両方の郵便番号に対応する

ユーザーが「1234567」と入力しても「123-4567」と入力しても動作するように設定できます。また、補完後に郵便番号フィールドをハイフンあり形式に統一することも可能です。

$(function () {
  $('#zip').jpostal({
    postcode: ['#zip'],
    address: {
      '#zip':  '%2',        // ハイフンあり形式に自動変換して上書き
      '#pref': '%3',
      '#city': '%4',
      '#town': '%5%6%7'
    }
  });
});

住所が見つからない場合のエラー処理

存在しない郵便番号が入力された場合、フィールドは空のままになります。callback オプションを使って住所が取得できなかった場合の処理を追加できます。

$(function () {
  $('#zip').jpostal({
    postcode: ['#zip'],
    address: {
      '#pref': '%3',
      '#city': '%4',
      '#town': '%5%6%7'
    },
    // 検索完了後のコールバック（data: 取得した住所データの配列）
    callback: function (data) {
      if (!data || data.length === 0) {
        // 住所が見つからない場合
        $('#zip-error')
          .text('この郵便番号の住所情報が見つかりませんでした。手動で入力してください。')
          .show();
        $('#pref, #city, #town').val('');  // 各フィールドをクリア
      } else {
        $('#zip-error').hide().text('');
      }
    }
  });
});

郵便番号バリデーションとの組み合わせ

郵便番号フィールドのフォーカスアウト時に形式チェックを行い、正しい形式のときだけ住所検索を実行する実装例です。

$(function () {
  // 郵便番号の形式チェック（7桁数字、またはハイフンあり）
  function isValidPostal(val) {
    return /^\d{7}$/.test(val) || /^\d{3}-\d{4}$/.test(val);
  }

  $('#zip').on('blur', function () {
    var val = $(this).val().trim();

    if (val === '') {
      $('#zip-error').hide();
      return;
    }

    if (!isValidPostal(val)) {
      $('#zip-error').text('郵便番号は7桁の数字またはハイフンあり形式（例: 123-4567）で入力してください').show();
      return;
    }

    $('#zip-error').hide();
  });

  // jpostal.jsでの自動補完（形式チェックはjpostal.jsが内部で処理）
  $('#zip').jpostal({
    postcode: ['#zip'],
    address: {
      '#pref': '%3',
      '#city': '%4',
      '#town': '%5%6%7'
    },
    callback: function (data) {
      if (!data || data.length === 0) {
        $('#zip-error').text('住所情報が見つかりませんでした').show();
      }
    }
  });
});

jpostal.js不要のVanilla JS版（フォールバック対応）

jQueryへの依存をなくしたい場合や、jpostal.jsが使えない環境向けに、郵便番号検索APIを直接Fetchするシンプルな実装例も紹介します。

// jQuery版（$.ajax）
function searchAddress(postal) {
  var code = postal.replace('-', '');  // ハイフンを除去
  if (!/^\d{7}$/.test(code)) return;

  $.ajax({
    url: 'https://zip-cloud.appspot.com/api/search',
    data: { zipcode: code },
    dataType: 'jsonp',
    success: function (data) {
      if (data.results) {
        var r = data.results[0];
        $('#pref').val(r.address1);  // 都道府県
        $('#city').val(r.address2);  // 市区町村
        $('#town').val(r.address3);  // 町域
      } else {
        alert('住所が見つかりませんでした');
      }
    }
  });
}

$(function () {
  $('#zip').on('blur', function () {
    searchAddress($(this).val());
  });
});

まとめ

jquery.jpostal.jsを使うと、数行のコードで郵便番号→住所の自動補完が実装できます。

• CDNで読み込み → $(el).jpostal({ postcode, address }) を設定するだけ
• フォーマットコード（%3〜%7）で補完フィールドを柔軟に設定できる
• callback で住所が見つからない場合の処理を追加する
• 郵便番号の形式チェックは blur イベントで事前に行う

関連記事: フォームバリデーション完全ガイド / blur()でフォーカスが外れた瞬間に処理する

よくある質問（FAQ）