jposta

Modern library for converting Japanese postal codes to addresses. 日本語の補足は最下部にあります。

Features

⚡ Simple usage with compatibility for modern frameworks ⚡ ES6 / Promise based / Typescript ready ⚡ No dependencies ⚡ Self-hosted & dynamic import (no implicit API calls)

Installation

$ npm install jposta

Usage

import { getAddress } from "jposta";

// pass zip code as string
const address = await getAddress("1000001");
console.log(address);
// { pref: "東京都", prefNum: 13, city: "千代田区", area: "千代田" }

// also you can pass zip code with hyphen
const address2 = await getAddress("100-0003");
console.log(address2);
// { pref: "東京都", prefNum: 13, city: "千代田区", area: "皇居外苑" }

Dynamic Import (Browser)

jposta requires hosting the data file in your project.

# Your project build
$ npm run build

> [email protected] 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

...and then you can import the data file dynamically.

const result1 = await getAddress("1000001");
// imports the data file named z10.js
const result2 = await getAddress("2100002");
// imports the data file named z21.js
const result3 = await getAddress("1000003");
// returns data without additional imports

Compatibility

ESM & CJS compatible. ESM is recommended.

Samples

• Vite + React + jposta (source code): https://nickichi.github.io/vite-react-jposta/
• Next.js(webpack) + jposta (source code): https://nickichi.github.io/nextjs-jposta/
• Node.js + Express + jposta: https://github.com/nickichi/node-express-jposta

License

see LICENSE

補足

• 郵便番号と住所は、日本郵便株式会社の郵便番号データを利用しています
• このライブラリは self-hosted な郵便番号検索を提供するために作成されました。外部 API を使用せず、バックエンドも不要です。ただし、ホストするアセットが 100 個増えます。
• クライアントサイドでの Dynamic Import を利用したくない場合は、サーバサイド（Node.js）に導入することで、簡単に郵便番号 API を構築できます(Samples 参照)。