今どきのフロントエンドのための、郵便番号→住所変換 #jposta

概要

入力された郵便番号から住所を自動入力するためのライブラリは無数に存在しますが、今どきのフロントエンドアーキテクチャと親和性の高いライブラリは多くありません。また、メジャーなライブラリの中にも郵便番号と住所の紐づけデータをAPIで外部から取得しているものがあり、エンタープライズで利用しにくいという状況があります。

そこで、jpostaの紹介です。
⚡ ES6 / Promiseベース / TypeScript対応
⚡ 依存ライブラリなし
⚡ Self-hosted & ダイナミックインポート (暗黙的なAPIコールなし)

https://www.npmjs.com/package/jposta
https://github.com/nickichi/jposta

インストール

$ npm i jposta
$ yarn add jposta
$ pnpm i jposta

使い方

簡単です。

import { getAddress } from 'jposta';

// 文字列で渡す
const address = await getAddress('1000001');
console.log(address);
// { pref: "東京都", prefNum: 13, city: "千代田区", area: "千代田" }

// ハイフンありも可
const address2 = await getAddress('100-0003');
console.log(address2);
// { pref: "東京都", prefNum: 13, city: "千代田区", area: "皇居外苑" }

仕組み

ダイナミックインポートで必要最小限のリソースを必要なタイミングで取得します。

const result1 = await getAddress('1000001');
// z10.jsのようなファイルをホスト先から取得
const result2 = await getAddress('2100002');
// z21.jsのようなファイルをホスト先から取得
const result3 = await getAddress('1000003');
// z10.jsはすでに取得済みなので余分な通信は必要なし

以下のように、検索アクションでデータファイルが取得されます。

データファイルはメインファイルにはバンドルされません。
例えば、viteでのビルドは下記のようになります。

$ npm run build

> vite-react-jposta@0.0.0 build
> tsc && vite build

vite v5.2.13 building for production...
✓ 136 modules transformed.
dist/index.html                         0.46 kB │ gzip:  0.30 kB
dist/assets/react-CHdo91hT.svg          4.13 kB │ gzip:  2.05 kB
dist/assets/index-DiwrgTda.css          1.39 kB │ gzip:  0.72 kB
dist/assets/z11-nic1O4vt-B_L_y_VH.js    2.29 kB │ gzip:  0.95 kB
dist/assets/z96-Br2qdTMP-DG7Gpu3V.js   80.14 kB │ gzip: 27.45 kB
...(many files)
dist/assets/z50-BWUSdQBW-BJcxw7Xg.js   87.66 kB │ gzip: 29.14 kB
dist/assets/z60-34YubQWJ-DwuyaedM.js  101.50 kB │ gzip: 29.97 kB
dist/assets/index-D0vWSNxA.js         152.48 kB │ gzip: 49.62 kB
✓ built in 2.16s

ご覧の通りですが、データファイルは各プロジェクトでホストしなければなりません。

参考1：Vite+React+jpostaサンプル
参考2：Next.js+jpostaサンプル

ダイナミックインポートで利用するのが最も簡単ですが、
場合によってはサーバサイドでデータ参照し、自前のAPIを構築するほうが望ましい場合もあります。

こちらのNode.js+Express+jpostaサンプルのように、サーバサイドで利用してAPI化することもできます。

データの出どころ？

データソースは日本郵便株式会社が提供しているCSVデータです。
ファイルの変更を監視＆自動反映します。

まとめ

Vite+React+TypeScriptなど、今どきのフロントエンドアーキテクチャとマッチする郵便番号ライブラリをお探しの方は、jpostaをぜひどうぞ。