郵便番号の住所自動入力が動かない原因まとめ（AjaxZip3・API別チェックリスト）

症状：エラーも出ないのに住所が入らない

郵便番号を入力しても都道府県や市区町村が自動で埋まらない。しかも開発者ツールのConsoleを開いても赤いエラーは何も出ていない。この「静かに何も起きない」状態が、住所自動入力でいちばん多いつまずき方です。JavaScriptの構文ミスなら赤いエラーが出るので気づけますが、住所自動入力が動かない原因の多くはコードは正常に実行されていて、ただ入れる先を見つけられていないタイプなので、エラーが出ません。

この記事は、住所自動入力の代表的な3つの実装方式（AjaxZip3・YubinBango・zipcloud APIを自作fetchで叩く）について、動かない原因を切り分けるチェックリストです。まず下の表で自分の症状に近い行を見て、該当セクションへ飛んでください。方式が分かっているなら、その方式のセクションだけ読めば直せる構成にしています。

まず3方式に共通する原因を確認する

方式を問わず起きる原因が先にあります。方式固有の話に入る前に、次の4つを潰してください。ほとんどの「エラーも出ないのに動かない」はこの範囲で解決します。

ここまでで直らなければ、方式ごとの固有原因に進みます。自分が使っている方式の節だけ読めば大丈夫です。

AjaxZip3が動かないとき

AjaxZip3は onkeyup などで AjaxZip3.zip2addr() を呼び、その引数に「どのフィールドに書き込むか」を name属性の文字列で渡す方式です。動かないときの固有原因はほぼ次の3つです。

下のデモで「フィールド名のずれ」を再現できます。チェックを切り替えると、書き込み先の指定が正しいときは住所が入り、間違っているときはエラーも出さずに何も入らないのが分かります（動作を手元で再現するためサンプル住所データを使っています。ライブラリ本体は読み込んでいません）。

<!-- 公式の配布URLをそのまま読み込む（charset必須） -->
<script src="https://ajaxzip3.github.io/ajaxzip3.js" charset="UTF-8"></script>

<input name="zip" onkeyup="AjaxZip3.zip2addr(this,'','pref','city','town');">
<input name="pref">  <!-- ← zip2addr の 'pref' とこの name を一致させる -->
<input name="city">
<input name="town">

ポイントは zip2addr() の第3引数以降と、書き込み先 input の name を完全に一致させることです。動かないときはこの対応表がずれていないかを最初に確認してください。

YubinBangoが動かないとき

YubinBangoはJavaScriptをほとんど書かず、決められたクラス名を付けるだけで動く方式です。そのぶん動かない原因も「クラス名の付け方」に集中します。

下のデモは「出力側のクラス名ミス」を再現したものです。チェックを外すと都道府県欄のクラス名が自己流になり、その欄だけ入らなくなります（こちらもサンプルデータで挙動を再現しています）。

<script src="https://yubinbango.github.io/yubinbango/yubinbango.js"></script>

<div class="h-adr">
  <span class="p-country-name" style="display:none;">Japan</span>
  <input class="p-postal-code" maxlength="8">      <!-- 郵便番号 -->
  <input class="p-region">                          <!-- 都道府県 -->
  <input class="p-locality">                        <!-- 市区町村 -->
  <input class="p-street-address">                  <!-- 町域以降 -->
</div>

クラス名は仕様で決まっているので、自己流に変えられません。埋まらない欄があるときは、その欄のクラス名が仕様どおりか（p-region／p-locality／p-street-address）を一つずつ確認してください。クラスを付けるだけで動く完成形は郵便番号 → 住所自動入力（ライブラリ版）の事例ページで触れます。

自作fetch（zipcloud API）が動かないとき

ライブラリを使わず、zipcloudの郵便番号検索API（https://zipcloud.ibsnet.co.jp/api/search?zipcode=…）を fetch で自分で叩く方式です。柔軟な反面、レスポンスの扱いで落とし穴が増えます。

下のデモは「正規化なし＋results未チェック」を再現します。チェックを外した状態でハイフン付き（例：100-0001）を入れると、住所が取れないうえに、該当なし時の null 参照で処理が止まる様子が分かります（APIは呼ばず、サンプルデータで挙動だけ再現しています）。

zipInput.addEventListener('input', function () {
  var digits = zipInput.value.replace(/[^0-9]/g, ''); // 数字だけにする
  if (digits.length !== 7) return;                    // 7桁そろってから

  fetch('https://zipcloud.ibsnet.co.jp/api/search?zipcode=' + digits)
    .then(function (res) { return res.json(); })
    .then(function (data) {
      if (data.results) {           // ← 該当なしは results が null。必ずガード
        var a = data.results[0];
        pref.value = a.address1;    // 都道府県
        city.value = a.address2;    // 市区町村
        town.value = a.address3;    // 町域
      } else {
        // 該当なし。手動入力を促すなどの分岐
      }
    })
    .catch(function () { /* 通信エラー時の分岐 */ });
});

自作版でつまずいたら、まず results が null になるケースを分岐しているかを確認してください。コピペで動く完成形は郵便番号自動入力（zipcloud API・自作fetch版）の事例ページにあります。ステータス表示や通信エラー時の分岐まで含めた実装を確認できます。

まとめ

住所自動入力が「エラーも出ないのに動かない」ときは、方式を問わずまず入れる先のフィールド指定と入力値の正規化を疑うのが最短ルートです。そのうえで方式ごとの固有原因を見ます。

AjaxZip3は zip2addr() の引数と name の一致、YubinBangoは h-adr と出力クラス名、自作fetchは該当なし時の results の扱い。ここが方式ごとの急所です。

どの方式でも、本番だけ動かないならhttp/https混在とCDNの読み込み失敗を先に潰してください。動く完成形を触りながら直したいときは、下の関連事例が対応します。

関連するUI事例

この記事の修正コードに対応する、コピペで動く住所自動入力の事例です。ライブラリ版と自作fetch版を並べて比較できます。

• 郵便番号 → 住所自動入力（YubinBango.jsライブラリ版）
• 郵便番号自動入力（zipcloud API・自作fetch版）