nihonpost

nihonpost is a TypeScript-first solution designed for efficient Japanese postal code lookup and address autofill in Vue 3 applications. This library functions entirely offline and requires no third-party dependencies, making it fully self-hostable. It features auto-updating data and is equipped to handle various input types, including full-width characters and the Japanese postal mark (〒).

Key Features

• Offline Capability: Operates without needing an internet connection or third-party API calls.
• Easy Integration: Works seamlessly out of the box with a simple configuration, providing zero-configuration functionality with CDN fallback.
• TypeScript Support: Fully typed environments ensure robust coding practices and improved developer experience.
• Vue 3 Composable: Specifically crafted as a composable for Vue 3, it employs a Promise-based API for intuitive usage.
• Input Normalization: Automatically normalizes full-width and postal mark inputs, improving user experience.
• Monthly Data Updates: The dataset is automatically updated monthly, ensuring that the postal code information remains current.

Usage Example (Vue 3)

Integrating nihonpost into a Vue 3 application is simple:

<script setup lang="ts">
import { usePostalCode } from 'nihonpost/vue'

const { code, address, loading, notFound } = usePostalCode()
</script>

<template>
  <label>郵便番号</label>
  <input v-model="code" placeholder="150-0002" />

  <span v-if="loading">検索中…</span>
  <span v-if="notFound">該当する住所が見つかりません</span>

  <template v-if="address">
    <input :value="address.prefecture" readonly />
    <input :value="address.city" readonly />
    <input :value="address.town" readonly />
  </template>
</template>

The composable listens for changes to the postal code field and automatically retrieves the matched address as soon as a valid entry is made.

Core Functionality without Vue

For applications not using Vue, the core library can be utilized directly, providing essential functionalities for postal code lookups:

import { lookup, lookupAll, formatPostalCode } from 'nihonpost'

const addr = await lookup('150-0002')
// { prefecture: '東京都', city: '渋谷区', town: '渋谷', ... }

The comprehensive dataset, which consists of around 124,000 postal codes, allows efficient chunk loading, ensuring that only necessary data is fetched based on user input. This keeps the application lightweight and responsive.

Custom Data Source Support

For those needing custom implementations, the loader can be configured to fetch from alternative sources, offering flexibility in usage:

configureLoader(async (prefix) => {
  const res = await fetch(`https://cdn.example.com/jp-postal/${prefix}.json`)
  return res.ok ? res.json() : null
})

Additional Capabilities

• Data Management: A built-in pipeline processes and rebuilds data monthly, accommodating applicable corrections and formatting.
• Multi-Municipality Handling: When postal codes relate to more than one municipality, all potential addresses can be fetched for user selection.

Data Source

The postal codes provided by nihonpost are sourced from Japan Post 郵便番号データ, ensuring reliable and accurate information.