Jpostcode

English: README.en.md

郵便番号から日本の住所を検索する JavaScript ライブラリです。フォームの住所自動入力など、外部 API を呼ばずにブラウザや Node.js だけで完結します。

バージョンは MAJOR.MINOR.YYYYMM 形式で、YYYYMM が収録データの年月です。上の npm version バッジがそのままデータの鮮度を表します(例: 1.0.202607 は 2026 年 7 月版データ)。

特徴

• 🔄 毎月自動更新 — 上流の jpostcode-data の更新を検知して新バージョンを npm に自動公開
• 🌐 公式 CDN あり — Cloudflare Pages からライブラリ本体と郵便番号データを配信
• ⚡ API サーバー不要 — ブラウザだけで完結
• 📖 カナ表記付き — 都道府県・市区町村・町域それぞれのカナを返す
• 🏢 事業所個別郵便番号対応 — 大口事業所の名称・番地を含むデータを収録
• 🔀 複数住所対応 — 同じ郵便番号に複数の住所が紐づく場合は全件を配列で返す
• 🧩 TypeScript 対応 — 完全な型定義付き
• 📦 Node / バンドラー / ブラウザ対応 — Node.js のほか、jpostcode/web で Vite / webpack などのバンドラーからも使える

提供形態

| 形態 | 読み込み方 | API | データの取得 | | --- | --- | --- | --- | | jpostcode(Node.js) | require / import | 同期 | パッケージ同梱の JSON をファイル読み込み | | jpostcode/web(バンドラー/ブラウザ) | import | Promise | CDN から上 3 桁ごとに fetch | | CDN スクリプト版 | <script> | Promise | 同上 | | CDN Bundle 版 | <script> | 同期 | 全データ同梱(約 55MB) |

クイックスタート(ブラウザ + CDN)

コピペで動きます。

<script src="https://jpostcode-js.pages.dev/dist/jpostcode-web.js"></script>
<script>
  Jpostcode.find('1000001').then(addresses => {
    console.log(addresses[0]?.prefecture); // 東京都
  });
</script>

ライブラリ本体・郵便番号データともに Cloudflare Pages から配信しています。データはデフォルトで公式 CDN から取得します。自前で配信する場合は Jpostcode.setBaseUrl('/data/json/') のように取得元を変更できます(データを自前で配信する)。

• 上流データの月次更新を反映して自動再配信
• 東京を含む Cloudflare エッジから低レイテンシで配信
• gzip / brotli 圧縮配信のため、1 回の検索で取得されるのは上 3 桁ごとの 1 ファイル・転送数 KB〜数十 KB
• JSON データには s-maxage=2592000(エッジ 30 日)/ max-age=86400(ブラウザ 1 日)のキャッシュヘッダ

フォーム住所自動入力の例

7 桁の郵便番号が入力されたら、都道府県・市区町村・町域を自動で埋める例です。

<input id="zip" placeholder="郵便番号(例: 1000001)">
<input id="prefecture" placeholder="都道府県">
<input id="city" placeholder="市区町村">
<input id="town" placeholder="町域">

<script src="https://jpostcode-js.pages.dev/dist/jpostcode-web.js"></script>
<script>
  document.getElementById('zip').addEventListener('input', async (e) => {
    const zip = e.target.value.replace(/[^0-9]/g, '');
    if (zip.length !== 7) return;

    const [address] = await Jpostcode.find(zip);
    if (!address) return;

    document.getElementById('prefecture').value = address.prefecture;
    document.getElementById('city').value = address.city;
    document.getElementById('town').value = address.town;
  });
</script>

インストール(npm)

npm install jpostcode

Node.js (CommonJS)

const { Jpostcode } = require('jpostcode');

const addresses = Jpostcode.find('0010000');
for (const address of addresses) {
  console.log(`${address.prefecture} ${address.city} ${address.town}`);
  console.log(`(カナ: ${address.prefectureKana} ${address.cityKana} ${address.townKana})`);
}

Node.js (ESM) / TypeScript

import { Address, Jpostcode } from 'jpostcode';

const addresses: Address[] = Jpostcode.find('0010000');
console.log(addresses[0]?.prefecture);

バンドラー(Vite / webpack)/ React などのフロントエンド

jpostcode/web を import します。本体は数 KB で、データは郵便番号の上 3 桁ごとに公式 CDN から fetch します(取得済みデータはメモリにキャッシュ)。

import { Jpostcode } from 'jpostcode/web';

const addresses = await Jpostcode.find('1000001'); // Promise<Address[]>
console.log(addresses[0]?.prefecture); // 東京都

React でフォームに住所を自動入力する例:

import { Jpostcode } from 'jpostcode/web';

function AddressForm() {
  const [address, setAddress] = useState({ prefecture: '', city: '', town: '' });

  const onZipChange = async (e: ChangeEvent<HTMLInputElement>) => {
    const zip = e.target.value.replace(/[^0-9]/g, '');
    if (zip.length !== 7) return;
    const [found] = await Jpostcode.find(zip);
    if (found) setAddress({ prefecture: found.prefecture, city: found.city, town: found.town });
  };

  return (
    <>
      <input onChange={onZipChange} placeholder="郵便番号" />
      <input value={address.prefecture} readOnly />
      <input value={address.city} readOnly />
      <input value={address.town} readOnly />
    </>
  );
}

データを自前で配信する場合はデータを自前で配信するを参照してください。

ブラウザ・Bundle 版(全データ同梱・同期 API)

すべてのデータを 1 ファイルに同梱した版です。ファイルは約 55MB(gzip 転送で約 4MB)と大きいものの、読み込み後はネットワークを使わず同期 API で呼び出せます。

<script src="https://unpkg.com/jpostcode@latest/dist/jpostcode-web-bundle.js"></script>
<script>
  const addresses = Jpostcode.find('1000001'); // Promise ではなく同期
  console.log(addresses[0]?.prefecture);
</script>

Bundle 版はファイルサイズが jsDelivr の配信上限(50MB)を超えるため、unpkg から読み込んでください。通常のフォーム用途には fetch 版(CDN スクリプト版または jpostcode/web)を推奨します。

データを自前で配信する

fetch 版はデフォルトで公式 CDN(jpostcode-js.pages.dev)からデータを取得します。このとき入力された郵便番号の上 3 桁が CDN へのリクエストとして送信されます。これを避けたい場合や、配信を自分の環境の管理下に置きたい場合は、データ一式を自前でホストできます。

1. npm パッケージに同梱されているデータ(JSON 951 ファイル・約 56MB)を静的配信ディレクトリにコピーします

   cp -r node_modules/jpostcode/dist/jpostcode-data/data/json public/data/json

2. 取得元を差し替えます

   Jpostcode.setBaseUrl('/data/json/');

• 実際に取得されるのは入力された郵便番号の上 3 桁に対応する 1 ファイル(数 KB〜数百 KB)だけです
• JSON は圧縮がよく効くため(全体で 56MB → gzip 後約 3.8MB)、配信側で gzip / brotli 圧縮を有効にすれば 1 ファイルあたりの転送量は数 KB〜数十 KB になります。ほとんどの静的ホスティング・CDN はデフォルトで圧縮配信します
• ライブラリと別のオリジンから配信する場合は、配信側に Access-Control-Allow-Origin ヘッダの設定が必要です(同一オリジンなら不要)
• データの更新は毎月の npm パッケージ更新に含まれます。npm update jpostcode 後に再コピーしてください

nginx で配信する場合の設定例です。nginx のデフォルトでは JSON は gzip 対象外のため、gzip_types の指定が必要です。

location /data/json/ {
    gzip on;
    gzip_types application/json;
    expires 1d;
    add_header Cache-Control "public";
    # 別オリジンのページから参照する場合のみ
    # add_header Access-Control-Allow-Origin "https://example.com";
}

API

Jpostcode.find(postalCode)

• 郵便番号は 7 桁の文字列で指定します。ハイフン付き('100-0001')も受け付けます
• 返り値は Address の配列です。同じ郵便番号に複数の住所が紐づく場合があるためです(複数町域、事業所個別郵便番号など)。存在しない郵便番号の場合は空配列を返します
• Node.js 版(jpostcode)は同期で Address[] を、Web 版(jpostcode/web / CDN スクリプト版)は Promise<Address[]> を返します
• Web 版は、データの取得に失敗した場合(ネットワークエラー、HTTP 5xx など)は Promise が reject します。「該当する住所がない」(空配列)とは区別されます

Address のプロパティ

| プロパティ | 型 | 例 | | --- | --- | --- | | zipCode | string | '1000001' | | prefecture | string | '東京都' | | prefectureKana | string | 'トウキョウト' | | prefectureCode | number | 13(JIS 都道府県コード) | | city | string | '千代田区' | | cityKana | string | 'チヨダク' | | town | string | '千代田' | | townKana | string | 'チヨダ' | | street | string \| null | '４−３−１城山トラストタワー２３階'(事業所個別郵便番号のみ) | | officeName | string \| null | '株式会社　スター・チャンネル'(同上) | | officeNameKana | string \| null | 同上のカナ表記 |

street / officeName / officeNameKana は事業所個別郵便番号(大口事業所)の場合に値が入り、通常の住所では null です。JSON.stringify(address) は上記プロパティ名の JSON を返します。

他のライブラリとの比較

npm で公開されている郵便番号検索ライブラリとの比較です(2026 年 9 月時点の npm 公開情報と、各ライブラリの README・型定義に基づく)。

| ライブラリ | 最終リリース | データの供給 | 型定義 | カナ | 事業所番号 | 複数住所 | | --- | --- | --- | --- | --- | --- | --- | | jpostcode | 2026-09(毎月自動) | 同梱 + CDN | あり | 都道府県〜町域 | あり | 全件 | | jposta | 2026-09 | 同梱 | あり | なし | なし | 1 件 | | jp-zipcode-lookup | 2025-06 | 同梱 | あり | 都道府県・市区町村 | なし | 全件 | | japan-postal-code-oasis | 2023-12 | 自前ホスト | なし | なし | なし | 1 件 | | japan-postal-code | 2023-07 | 外部サイト | なし | なし | なし | 1 件 | | yubinbango-core2 | 2019-05 | 外部サイト | なし | なし | なし | 1 件 |

• 最終リリース: npm 上の最新バージョンの公開年月。jpostcode は上流データの月次更新に追随して自動公開されます
• データの供給: 「同梱」はパッケージにリリース時点のデータを含むもの、「自前ホスト」はデータを自分で配信する必要があるもの、「外部サイト」は作者が用意したサイトから取得するもの。yubinbango-core2 のデータは yubinbango.github.io 側で 2026-05 に更新されています
• 事業所番号: 大口事業所個別郵便番号の名称・番地を返すかどうか
• 複数住所: 同じ郵便番号に複数の住所が紐づく場合に全件を配列で返すか、1 件だけ返すか

データの鮮度について

• 上流の jpostcode-data が月次で日本郵便の最新データを取り込みます
• 本ライブラリは GitHub Actions で上流の更新を検知し、新バージョンを自動で npm / CDN に公開します
• バージョン MAJOR.MINOR.YYYYMM の YYYYMM がデータ取得時期を表します(例: 1.0.202607 は 2026 年 7 月版)
• npm を使う場合は依存を更新するだけ、CDN を使う場合は何もしなくても最新になります

デモ

ライブデモ: https://matzlika.github.io/jpostcode-js/

ローカルで動かす場合:

npm install
npm run build
mkdir -p docs/dist && cp -r dist/* docs/dist/
npx http-server docs -p 8000

開発

npm install
npm run build  # CommonJS / ESM / jpostcode/web / ブラウザ版を生成
npm test

貢献

issue や Pull Request を歓迎します。

謝辞

このライブラリは jpostcode-data (Copyright 2023 SmartHR, Inc., MIT License) のデータを使用しています。メンテナと貢献者の皆様に感謝いたします。

ライセンス

MIT。サードパーティ著作権表示は NOTICE を参照してください。