postal-jp

TypeScript 向けの郵便番号住所検索ライブラリです。Core はフレームワークや DOM に依存せず、データ提供元は Provider として差し替えられます。既定の YubinBangoProvider はブラウザでのみ利用できます。

このプロジェクトについて

このライブラリは YubinBango から着想を得ています。

YubinBango は郵便番号から日本の住所を自動入力するためのシンプルで便利な仕組みを提供していますが、その API は主に DOM の直接操作と特定の CSS クラス名を前提として設計されています。

本プロジェクトは同じ一般的なユースケースを、Vue 3 や Nuxt などのリアクティブフレームワークへ統合しやすい、モダンな TypeScript ファーストの API として再実装したものです。

Core ライブラリはフレームワーク非依存であり、DOM を直接操作しません。Vue 固有の機能は Composable として別途提供します。

本プロジェクトは YubinBango の公式プロジェクトではありません。

yubinbango-core のソースコードはコピーまたは直接改変していません。本プロジェクトの実装は、YubinBango の公開された挙動と設計上の考え方を参照しつつ、独自に作成したものです。

郵便番号データは、YubinBango プロジェクトが公開するデータソースから取得します。

ライセンスの詳細は LICENSE を参照してください。

Installation

npm install postal-jp

Vue を使用する場合は Vue もインストールします。

npm install postal-jp vue

Core usage

import { lookupAddress } from 'postal-jp'

const address = await lookupAddress('530-0001')

console.log(address)
// { postalCode: '5300001', prefectureCode: '27', ... }

lookupAddress は入力を正規化します。形式が不正、または該当データがない場合は null を返します。通信やデータ形式の失敗は PostalCodeError の派生エラーとして reject されます。

独自のデータソースは PostalCodeProvider を実装して渡せます。

import { lookupAddress, type PostalCodeProvider } from 'postal-jp'

const provider: PostalCodeProvider = {
  async lookup(postalCode, { signal } = {}) {
    const response = await fetch(`/api/postal-code/${postalCode}`, { signal })
    return response.ok ? response.json() : null
  },
}

const address = await lookupAddress('530-0001', { provider })

Vue usage

import { useYubinBango } from 'postal-jp/vue'

const { lookup, loading, error, result, reset } = useYubinBango()
const address = await lookup('530-0001')

Composable は入力値を監視しません。必要ならアプリ側の watch などから、7 桁に正規化できた時点で lookup を呼んでください。

Nuxt 4 usage

既定 Provider は JSONP を使うブラウザ専用の実装です。Nuxt ではクライアント側でだけ検索します。

const { lookup } = useYubinBango()

if (import.meta.client) {
  await lookup('530-0001')
}

サーバー側でも検索する場合は、サーバー API を呼ぶ独自 PostalCodeProvider を渡してください。

謝辞

本プロジェクトは YubinBango から着想を得ており、YubinBango プロジェクトが公開する郵便番号データを外部データソースとして使用します。

YubinBango は MIT License のもとで配布されています。

yubinbango-data リポジトリは YubinBango プロジェクトの一部として管理され、YubinBango の郵便番号データソースとして利用されています。

本プロジェクトは yubinbango-core のソースコードをコピーまたは直接改変していません。TypeScript API およびフレームワーク連携は、モダン JavaScript、Vue 3、Nuxt 環境向けに独自実装しています。

詳細は LICENSE を参照してください。

License

MIT. このリポジトリには yubinbango-core のソースコードは含まれていません。既定 Provider は YubinBango の公開データ配信方式を参照しています。