Contact Form 7でzipaddr-jpが動かなかった話｜郵便番号→住所自動入力で踏んだid命名規則の罠

プレビュー画面で、郵便番号欄に「520-3041」と入れました。何も起きません。フォーカスを次の欄に移しても、住所欄は空のまま。エラーも出ない。Contact Form 7 に zipaddr-jp を入れて、郵便番号を打てば住所が自動で埋まる、はずでした。先に答えを書いてしまうと、原因は id 命名規則の area を1行書き忘れていたこと。しかもこれは、プラグイン作者自身が「誤って定義する方が多い」と注記しているくらい、誰もがハマる場所でした。以下、その「動かない」をどう切り分けたかを、受託案件の流れと一緒に書き残しておきます。

先に2枚だけ図を見せます。1枚目が今回の罠そのもの(id は5項目あるのに4項目で書いてしまう)、2枚目がプラグインのデータの流れです。

確認日：2026年5月8日。本記事の情報は、WordPress.org の zipaddr-jp プラグインページ、zipaddr-jp 公式サイト、Contact Form 7 公式サイトをもとにしています。
検証環境：Local by Flywheel / WordPress 6.9.4 / PHP 8.3.21 / Contact Form 7 ・ zipaddr-jp（いずれも2026年5月時点の最新版）。本番投入したクライアントサイトは2025年から稼働中で、月数十件の問い合わせが滞りなく送信されています。

受託案件、郵便番号→住所の自動入力

受けた依頼は、はっきりしていました。すでに Contact Form 7 で動いている問い合わせフォームに、郵便番号入力欄と住所欄を追加したい。郵便番号を入れると、都道府県・市区町村・町域までが自動で埋まるようにしてほしい。番地と建物名は、ユーザーが自分で入力する想定です。WordPress を仕事で使っていると、似た依頼に何度か出会います。問い合わせフォームの離脱率を下げたい、という運用上の動機がはっきりしているケースが多くて、自分の経験では「住所を何度も書かせない」設計のほうが、最終的なコンバージョンが地味に上がります。とはいえ、住所の自動入力を自前で作ろうとすると意外と泥沼です。郵便番号と住所の対応データをどこから取るのか。データの更新はどうするのか。API を叩くなら通信失敗時のフォールバックはどうするのか。受託のスコープでこれを一から設計するのは、見積もりの何倍も時間がかかる。だから、ライブラリやプラグインの選定が、実際の作業の半分以上を占めます。

プラグイン選定、行き着いた zipaddr-jp

WordPress.org でプラグインを検索すると、郵便番号→住所自動入力で実用上の選択肢になるのは zipaddr-jp に絞られていきます。作者の 公式サイトによると、Welcart、Contact Form 7、MW WP Form、Trust Form、WooCommerce、Ninja Forms、WP-Members、WPForms、Visual Forms Builder、JetFormBuilder と、主要な日本語フォームプラグインがほぼ網羅されています。仕組みはシンプルです。郵便番号の入力欄に値が入ると、プラグインの JavaScript がそれを拾って zipaddr 側のサーバーに jsonp 形式で問い合わせを送る。返ってきた都道府県・市区町村・町域のデータを、フォーム上の対応する input に自動で書き込んでくれる。先ほどの1枚目の図が、その流れです。面白かったのは、対応一覧の「Contact Form 7 標準サポート」という記述でした。Contact Form 7 のフォームタグに、決められた id を付けるだけで連携できる、と書いてあります。たとえば郵便番号欄なら [text* your-postcode id:zip] のように、id オプションで zip を指定する書き方です。

余談ですが、「id 規則を守れば動く」というシンプルな統合方式は、Contact Form 7 のように HTML 出力をプラグイン側で組み立てるツールとの相性がよいです。HTML を直接書く案件で使う yubinbango.js のように form 要素や input のクラス名を細かく指定する方式は、Contact Form 7 では微調整がしにくい。id 規則だけで完結する zipaddr-jp の設計は、WordPress 側に寄り添っている、という印象でした。

Contact Form 7 への組み込み

管理画面でプラグインを検索してインストール、有効化。これでサイドバーに「Zipaddr-JP」というメニューが追加されます。設定画面を開くと、郵便番号区切り文字、入力後にフォーカスを移動するか、プレースホルダーをどう書くか、といった項目が並んでいて、最初はどれもデフォルトのままで動きます。続いて Contact Form 7 のフォームタグに id を仕込みます。私のフォームは、郵便番号・都道府県・市区町村・町域・以降の住所、と分けて入力させる構成だったので、こんなマークアップになります(実際のラベル文言などは案件に合わせて調整しています)。

id 名は zip / pref / city / area / addr の5項目。これらが、郵便番号・都道府県・市区町村・町域・以降の住所、にそれぞれ対応します。zipaddr-jp は最大6グループまで同時利用できる設計で、2グループ目以降は zip2 / pref2 / city2 / area2 / addr2 と末尾に番号を付ける命名規則です。下の対応表のとおりです。

ここまでの設定だけで、本来は動くはず。というのが公式ドキュメントの記述です。ただ、私はこの設定を一発で正しく書けず、最初の試運転で見事につまずきました。

動かない。エラーも出ない

プレビューで「520-3041」と入れる。何も起きません。フォーカスを次の欄に移しても、住所欄は空のまま。最初に疑ったのは、プラグインの読み込み失敗でした。開発者ツールを開いて、コンソールを確認。エラーは出ていません。Network タブを見ると、zipaddr 側の API へのリクエストは飛んでいて、200 で返っている。レスポンスの中身を覗くと、ちゃんと「滋賀県」「栗東市」「出庭」のデータが入っています。つまり、プラグインは正しく動いている。郵便番号も拾えている。住所データもサーバーから返ってきている。なのに、フォームの input には何も書き込まれない。こういう「途中までは正常、最後だけ無音」というケースは、たいてい書き込み先の指定がずれています。プラグイン側がデータを書き込もうとしている input が、フォーム上に存在しないか、別の名前になっているか。そこで、フォームタグに付けた id を見直し始めました。そして、自分のフォームタグを読み返して、ようやく気づきます。id を addr しか付けていない。町域用の area が、丸ごと抜けていました。最初に「住所の自動入力」と聞いて、都道府県・市区町村・住所詳細の3つに分けるイメージで設計していたのです。pref / city / addr の3つで完結する、と思い込んでいました。

area と addr が分かれている理由

zipaddr-jp の area と addr は、設計思想として役割がきっちり分かれています。area は、郵便番号から特定できる「町域」の部分。郵便番号「520-3041」を例にすると、ここに入るのは「出庭」です。zipaddr 側のデータベースは、都道府県・市区町村・町域までを返してくれますが、それより先、番地や建物名・部屋番号は、郵便番号からは特定できません。だから addr は、ユーザー自身が入力する欄として、別に用意されています。言い換えれば、area は「自動補完される最後の input」、addr は「ユーザーが自分で書く最初の input」、というコントラクトです。両者を1つにまとめてしまうと、自動補完の結果と、ユーザー入力の番地・建物名が同じ input に同居することになって、補完のタイミングや値の置き換えで挙動が崩れます。下の図が、その境界です。

area 用の input をフォームタグに1行追加し、町域は自動補完欄、番地・建物名はユーザー入力欄、と役割を分けたら、すんなり動きました。郵便番号「520-3041」を入れると、滋賀県 / 栗東市 / 出庭 が一瞬で埋まり、最後の番地欄にカーソルが移ります。クライアントにも気持ちよく使ってもらえる体験になりました。

本番前のテスト郵便番号

1件の郵便番号で動いたからといって、すぐ本番投入してはいけない、と案件のたびに思い知ります。郵便番号と住所の対応には、思ったよりたくさんのエッジケースがあります。本番前に、私が最低限テストする郵便番号を表にしておきます。

受託のサイトでは、こうした特殊ケースを数件まとめてテストして、すべてで自然に補完されることを確認してから引き渡しました。クライアントの問い合わせフォームでは想定読者の所在地に偏りがあるかもしれませんが、テストの段階では地理的な分布を意識して郵便番号を選んでおくと、本番投入後の「動かない」報告が減ります。

静的 HTML なら yubinbango.js

WordPress を使わない案件、たとえばランディングページや独立した申し込みフォームを HTML / CSS だけで組む場面では、yubinbango.js が定番です。私は受託で本番投入したことはなく、自作の HTML ページに組み込んで動作テストをした程度ですが、設置の手軽さは zipaddr-jp とは別系統の魅力があります。特徴は、microformats（h-adr）の規格に沿ったクラス名で動くこと。フォーム要素に class="h-adr" を付けて、国名指定、郵便番号欄、各住所欄に決められたクラス名を振ります。対応は下の表のとおりです。

WordPress と組み合わせるとき、Contact Form 7 や WPForms のようにフォームプラグイン側が HTML を組み立てる仕組みでは、class="h-adr" を form 要素に付けるのが意外と面倒です。プラグインによっては form 要素にクラスを追加するオプションがあったり、無かったりします。WordPress 案件では zipaddr-jp の id 規則のほうが扱いやすい、というのが私の感覚です。逆に、WordPress を使わない静的 HTML や、フォームを自作している React / Vue 環境だと、yubinbango.js の microformats アプローチのほうがシンプル。「フォームに1つクラスを付けるだけ」という設計の素直さが効いてきます。

触らなかった選択肢（KEN_ALL.csv / zipcloud / postcode-jp）

正直に書くと、今回の案件では他の選択肢を本格検討しませんでした。zipaddr-jp で要件が満たせるとわかった時点で深掘りはやめたので、ここは「触らなかったが存在を把握している」レベルの記述です。3つを表にしておきます。

受託のクライアント案件では、追加の月額コストを発生させずに WordPress 内で完結する zipaddr-jp が、ちょうどよい落としどころでした。エンタープライズ案件で SLA が必須になる場面では、postcode-jp や類似の有料サービスが候補に上がってくると思います。

モバイルの一手間、inputmode と autocomplete

住所自動入力が動くようになって、もう一段の体験改善を入れたくなりました。スマホで郵便番号を入力するとき、フリックキーボードのまま数字を打たせると、視線とタップ数が増えます。郵便番号の input には inputmode="numeric" を指定して、最初から数字キーボードが立ち上がるようにしておくと、入力の負担が下がる。もうひとつ、autocomplete="postal-code" も合わせて指定しました。これはブラウザに「この input は郵便番号です」と教えるヒントで、過去に入力した郵便番号を、ブラウザの保存値から自動補完してくれます。同じユーザーが何度か問い合わせるサイトでは、これが効きます。Contact Form 7 のフォームタグには inputmode や autocomplete を直接書く構文がないため、こんな書き方で属性を追加しました。

Contact Form 7 のフォームタグには、未知のオプション名を書いてもエラーにならず、HTML 属性として出力する挙動があります。inputmode:numeric や autocomplete:postal-code は、それぞれ inputmode="numeric"、autocomplete="postal-code" として最終的な input に反映されます。同じ要領で、各住所欄にも autocomplete="address-level1"（都道府県）、address-level2（市区町村）、address-line1（町域）、address-line2（以降）を指定しておくと、ブラウザのオートフィル機能とも噛み合います。都道府県・市区町村・町域は zipaddr-jp が自動入力してくれるので、ユーザーが手で入力するケースは少ないのですが、オートフィル候補が出ること自体に意味がある。「住所を覚えてくれているサイト」という体験は、フォーム送信のハードルを下げます。

本番投入後の体感

クライアントのサイトは2025年から稼働中で、月数十件の問い合わせがこのフォームから送信されています。住所自動入力が原因で問い合わせが止まった、という報告は、稼働開始から今まで一度もありません。zipaddr 側のサービスが万一止まっても、ユーザーが手で住所を入力すれば送信は通る作りにしてあるので、致命的な障害にはならない設計です。体感として、住所入力のハードルが下がったことで「フォームに途中まで書いて諦める」という離脱が減った、という話を、クライアントから後日聞きました。具体的な数値までは追えていませんが、月数十件の送信が安定して続いているのは、フォーム周りの摩擦が小さくなった効果だと思います。

もう一度、520-3041 を入れてみる

冒頭の場面に戻ります。あのとき「520-3041」を入れても、住所欄は空のままでした。いま同じ郵便番号を入れると、滋賀県 / 栗東市 / 出庭 が一瞬で埋まって、カーソルが番地欄に移ります。差は、area の1行だけでした。今回いちばん効いたのは、「インストールするだけで動く」と書かれたプラグインでも、id 命名規則のような小さなコントラクトは存在する、という当たり前の事実です。それを読み飛ばすと、API は動いていて、レスポンスも返っていて、エラーも出ない、という「途中までは正常、最後だけ無音」のデバッグに小一時間吸い取られます。公式ドキュメントの太字注記は、飛ばさない。「自分は気をつけるから大丈夫」と思った瞬間に、誤って定義する方の一人になります。

もうひとつ、次の自分に渡しておきたいのは、area と addr のように「機械が埋める欄」と「人が埋める欄」を分ける、という発想です。郵便番号と住所に限らず、姓と名、メールアドレスと確認用、検索キーワードと絞り込み条件、といった具合に、自動化を扱うときはこの境界が必ず出てきます。今回はそこを1つの input に押し込めようとしてつまずきました。次にライブラリを選ぶときは、「データの流れ」と「ユーザー操作の流れ」を、フォーム設計に持ち込む前に分けて考える。この順序だけは、忘れないでおきます。同じく Contact Form 7 と zipaddr-jp で「動かない」と詰まっている方は、まず id 命名規則の area が抜けていないか、そこを見てみてください。私と同じ理由でハマっている可能性が、それなりに高いと思います。

関連記事

• 日本語入力のEnterでフォームが誤送信される問題を直した話｜Safari・React・Vue対応 ── 同じ WordPress フォーム実装で、IME 確定の Enter による誤送信を直した記録。
• 姓名フォームのフリガナ自動入力をcompositionイベントで自前実装した話 ── IME の composition イベントで、姓名フォームのフリガナ自動入力を自前で組んだ話。
• 日本語フォームの半角カナ・全角英数を input と blur で使い分けて自動変換する話 ── 半角カナや全角英数を、input と blur で役割分担しながら自動変換する話。

本記事の情報は2026年5月8日時点のものです。zipaddr-jp や Contact Form 7 のバージョンアップにより、設定方法や対応フォームが変わる可能性があります。最新情報は、WordPress.org の zipaddr-jp プラグインページおよび zipaddr-jp 公式サイトで確認することをおすすめします。