jp-postal-json

TypeScript client for Japanese postal codes

jp-postal-json

A small TypeScript client for Japanese postal code address lookup.

日本の郵便番号から住所候補を取得するための、小さな TypeScript ライブラリです。

npm GitHub Demo

Install

Install from npm

npm install jp-postal-json

Usage

Lookup from TypeScript

Convenience function

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

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

Reusable client

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

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

Demo

Try a postal code lookup

This demo uses the same hosted static data as the default client.

Enter a postal code and run lookup.

Hosted static data

Static JSON data behind the client

By default, jp-postal-json uses hosted static JSON data. For production use, consider caching, mirroring, or self-hosting the data depending on your requirements.

jp-postal-json は、デフォルトでは hosted static JSON data を参照します。 本番利用では、必要に応じてキャッシュ、ミラー、自社ホストを検討してください。

Client default

  • The package fetches prefix data internally when lookup is called.
  • The hosted data is an implementation detail of the default client.
  • Missing prefixes are treated as no data.

Self-hosting option

  • Prefix JSON data can be cached, mirrored, or self-hosted.
  • Use baseUrl when you operate your own static data host.
  • The hosted JSON cache is currently one hour.

Data source

Address data is based on public postal code data from Japan Post. Metadata includes data update time, generation time, and record counts.

Production use / No SLA

Use hosted data carefully

jp-postal-json and its hosted static data are provided as-is. There is no SLA and no warranty for availability, accuracy, continued operation, data freshness, or fitness for a particular purpose.

For production use, consider cache, mirror, or self-hosting options when your application has specific availability, latency, retention, or auditability requirements. Treat hosted data as convenient default data, not as a guaranteed production dependency.

Links

Project resources

npm package GitHub repo Hosted static data