Japanese postal code lookup for TypeScript

郵便番号から住所へ、
関数ひとつで。

jp-postal-json は日本の郵便番号を扱うための軽量な TypeScript ライブラリです。正規化・検証・住所ルックアップを、依存パッケージなしで提供します。

v0.2.0
TypeScript first
Zero dependencies
MIT License

はじめるデモを試す GitHub

npm install jp-postal-json

lookup.ts TypeScript

import { lookupPostalCode } from "jp-postal-json";

const addresses = await lookupPostalCode("100-0001");

console.log(addresses[0]);
// {
//   postalCode: "1000001",
//   prefecture: "東京都",
//   city: "千代田区",
//   town: "千代田"
// }

Features

小さく、確かに動く

住所入力フォームに必要な道具だけを、最小限の API で。

入力の正規化

全角数字・ハイフン・空白の混在をそのまま受け付け、7桁の数字に正規化します。

バリデーション

validatePostalCode で郵便番号として妥当かどうかを 1 行で判定できます。

依存ゼロ・軽量

外部依存はありません。住所データは同梱せず、必要なときに必要な分だけ取得します。

プレフィックス分割データ

先頭3桁ごとの静的 JSON を取得する設計で、転送量を小さく抑えます。

メモリキャッシュ内蔵

同じプレフィックスの再取得を自動でスキップ。cache: false で無効化もできます。

セルフホスト対応

baseUrl を差し替えるだけで、自前でホストした JSON データを参照できます。

Install

インストール

npm install jp-postal-json

pnpm add jp-postal-json

yarn add jp-postal-json

bun add jp-postal-json

Usage

使い方

単発のルックアップには関数を、繰り返し使う場面ではクライアントを。

かんたんに使う

import { lookupPostalCode } from "jp-postal-json";

const addresses = await lookupPostalCode("100-0001");
// [{ prefecture: "東京都", city: "千代田区", ... }]

クライアントを再利用する

import { createPostalCodeClient } from "jp-postal-json";

const client = createPostalCodeClient();

await client.lookup("100-0001"); // /100.json を取得
await client.lookup("100-0005"); // キャッシュを再利用

ユーティリティ関数

import {
  normalizePostalCode,
  validatePostalCode,
  getPostalCodePrefix
} from "jp-postal-json";

normalizePostalCode("１００-０００１"); // "1000001"
validatePostalCode("100-0001");        // true
getPostalCodePrefix("100-0001");       // "100"

セルフホストしたデータを使う

import { createPostalCodeClient } from "jp-postal-json";

const client = createPostalCodeClient({
  baseUrl: "https://example.com/postal/v1"
});

const addresses = await client.lookup("100-0001");

Demo

ブラウザで試す

このデモは、デフォルトのクライアントと同じホスト済み静的データを使っています。

郵便番号を入力して検索してください。

API Reference

API リファレンス

`normalizePostalCode(input)`

(input: string) => string

郵便番号の入力を数字のみに正規化します。

全角数字を半角数字に変換
ハイフン（半角・全角）、空白、その他の非数字文字を除去

`validatePostalCode(input)`

(input: string) => boolean

正規化後の入力がちょうど 7 桁の数字であれば true を返します。

`getPostalCodePrefix(input)`

(input: string) => string | null

正規化・検証を通過した郵便番号の先頭 3 桁を返します。不正な郵便番号には null を返します。

`buildPostalCodeDataUrl(input, options?)`

(input: string, options?: { baseUrl?: string }) => string | null

郵便番号プレフィックスに対応する静的 JSON データの URL を構築します。 URL を組み立てるだけで、fetch は行いません。

buildPostalCodeDataUrl("100-0001");
// "https://data.jp-postal.com/v1/100.json"

`createPostalCodeClient(options?)`

(options?: PostalCodeClientOptions) => PostalCodeClient

住所ルックアップ用のクライアントを作成します。

baseUrl — 参照する静的データのベース URL（既定は https://data.jp-postal.com/v1）
fetcher — テストやカスタムランタイム向けに fetch 実装を注入
cache — プレフィックス JSON のメモリキャッシュ（既定で有効、false で毎回取得）

プレフィックス JSON が 404 を返す場合、ルックアップは例外を投げず空配列を返します。その他の HTTP エラー・ネットワークエラー・JSON パースエラー・不正なレスポンス構造は例外になります。

await client.lookup("000-0000"); // []（データなし）
await client.lookup("abc");      // []（不正な入力）

client.clearCache(); // キャッシュをリセット

`lookupPostalCode(input, options?)`

(input: string, options?: LookupPostalCodeOptions) => Promise<PostalAddress[]>

クライアントを明示的に作らずに住所を検索する便利関数です。オプションは PostalCodeClientOptions に加えて signal（AbortSignal）を受け付けます。

Types

export type PostalAddress = {
  postalCode: string;
  prefecture: string;
  city: string;
  town: string;
  prefectureKana?: string;
  cityKana?: string;
  townKana?: string;
};

export type PostalCodeClient = {
  lookup(input: string, options?: PostalCodeLookupOptions): Promise<PostalAddress[]>;
  clearCache(): void;
};

export type PostalCodeClientOptions = {
  baseUrl?: string;
  fetcher?: typeof fetch;
  cache?: boolean;
};

Hosted static data

静的 JSON データについて

jp-postal-json はデフォルトで https://data.jp-postal.com/v1 のホスト済み静的 JSON データを参照します。住所データは npm パッケージには同梱されません。

クライアントの既定動作

ルックアップ時に先頭 3 桁ごとのプレフィックス JSON を内部で取得します。
ホスト済みデータはデフォルトクライアントの実装詳細です。
存在しないプレフィックスは「データなし」として扱われます。

セルフホストという選択肢

プレフィックス JSON はキャッシュ・ミラー・セルフホストが可能です。
自前の静的データホストを使う場合は baseUrl を指定してください。
ホスト済み JSON のキャッシュ時間は現在 1 時間です。

データソース

住所データは日本郵便が公開している郵便番号データに基づいています。メタデータにはデータ更新日時・生成日時・件数が含まれます。

Production use / No SLA

本番利用時の注意

jp-postal-json およびホスト済み静的データは現状のまま（as-is）提供されます。可用性・正確性・継続運用・データ鮮度・特定目的への適合性について、SLA や保証はありません。

可用性・レイテンシ・データ保持・監査性の要件があるアプリケーションでは、キャッシュ・ミラー・セルフホストの利用を検討してください。ホスト済みデータは「便利なデフォルト」であり、保証された本番依存先ではありません。