zipcode-lookup

日本郵便が公開する郵便番号データ(UTF-8版 KEN_ALL)をダウンロードして、郵便番号⇄住所をローカル検索するスキル。APIキー不要。約12万件の全データを手元に持つので、件数制限なく繰り返し検索できる。

実測日: 2026-09-12。本文のコマンド・構造は実測で確認したものを収録(個所ごとの日付は各所の記載を参照)。

基本の流れ

1. データをダウンロードする

ダウンロードページはここ(2026-09-11にページ構造を確認):

curl -sm 30 -L -o utf-zip.html https://www.post.japanpost.jp/zipcode/dl/utf-zip.html

ページ内の「全国一括」のリンク(2026-09-11時点で utf/zip/utf_ken_all.zip)を取り出してダウンロードする。

href=$(grep -oE 'utf/zip/utf_ken_all\.zip' utf-zip.html | head -1)
curl -sm 120 -L -o utf_ken_all.zip "https://www.post.japanpost.jp/zipcode/dl/${href}"
unzip -o utf_ken_all.zip   # KEN_ALL.CSV (UTF-8) が出てくる

直リンクを推測で書かない。 必ずページを経由して、そのとき記載されているリンクを使う。

データセンター系IPからはzipをダウンロードできない(重要)。 2026-09-11と2026-09-12の実測では、データセンター系IPからのアクセスではzipが(ページから取り出した正規リンク・ブラウザ相当のUser-Agentでも)すべて404を返した。ダウンロードページ自体は200で見えるので「ページは開けるのにzipだけ404」なら、このIP制限にかかっている可能性が高い。クラウド上のエージェント実行環境はだいたいデータセンターIPなので、この環境ではダウンロード自体が成立しないことに注意。その場合の代替:

1. ユーザーに自分のPC(住宅回線)で utf_ken_all.zip をダウンロードしてもらい、ファイルを渡してもらう。
2. ユーザー側のマシンでこのスキルの手順を実行してもらう。
3. どちらも無理なら「この実行環境のIPからは日本郵便のデータを取得できない」と明示し、推測の値を答えない。

差分だけ欲しい場合は、同じページに「更新データ(追加・廃止・変更)」の月次zipがある。

2. 検索する

# 郵便番号 → 住所 (ハイフンなし7桁で検索)
grep '"1000001",' KEN_ALL.CSV   # 千代田区千代田(皇居)

# 住所 → 郵便番号 (部分一致)
grep '丸の内' KEN_ALL.CSV

読み方(CSVの列)

1行15列。文字列フィールドはすべてダブルクォートで囲まれている(郵便番号は "1000001" の形)。主要な列は: 1列目=全国地方公共団体コード、3列目=郵便番号(7桁)、7列目=都道府県名、8列目=市区町村名、9列目=町域名(4〜6列目はそれぞれのカナ表記)。

• 町域名が「以下に掲載がない場合」の行は、その市区町村で町域の記載がない地域すべてに対応する。
• 1つの郵便番号に複数行(複数町域)が対応することがある。最初の1行で打ち切らず、該当行をすべて返す。

更新サイクル

郵便番号データは月次で更新される(月末に当月分が公開)。検索のたびに取り直す必要はないが、「何月分のデータか」をユーザーに伝えられるように、ダウンロード日を控えておく。古いデータで廃止・変更された番号を案内しないよう、月1回程度は取り直す。

エラー・失敗時の対応

共通の取得時チェックリストは 共通レスポンス契約 の「取得時の落とし穴チェックリスト」を参照。

• zipが404/403/タイムアウト: 推測したURLを叩いていないか確認し、ダウンロードページからリンクを取り直す。ページは開けるのにzipだけ404が続くなら上記のデータセンターIP制限の可能性が高い。代替手順(ユーザー側でのダウンロード)を案内し、それでも駄目なら「日本郵便のサイトからデータを取得できなかった」と明示してページのURLを案内する。
• 住所が見つからない: 町域名は郵便事業上の表記で、住居表示と異なることがある。丁目・番地を削って町域名の部分一致で探し直す。大字・小字はデータに含まれないことがある。
• 文字化け: UTF-8版を使っている限り化けない。もし文字化けするならJIS版(ken_all.zip、Shift_JIS)を落としている可能性が高い。UTF-8版を取り直す。

注意

• 返す住所は郵便番号のための公式表記であり、住居表示・登記上の表記と一致しないことがある。「郵便番号データ上の表記」であることを必要に応じて伝える。
• データの基準日(何月分か)を添えて答える。

English summary

Look up Japanese postal codes and addresses both ways using Japan Post's official KEN_ALL dataset (UTF-8 edition). No API key or login: download the national zip from the official download page and search locally. Never guess the zip's direct URL - datacenter IPs were served 404s for direct zip links on 2026-09-11 while the page itself returned 200; always extract the current link from the page. Data is updated monthly; tell the user which month's dataset you searched. Address spellings are Japan Post's postal notation, which can differ from residential addressing.