Jpostcode

Jpostcodeは、郵便番号から日本の住所を検索するためのライブラリです。都道府県、市区町村、町域名を、漢字とカナの両方で詳細に提供します。

🗓 毎月自動更新: 上流の jpostcode-data が日本郵便の最新データを取り込むたびに、本ライブラリも自動的に新バージョンを npm に公開します。郵便番号データを最新に保つために、依存関係を更新するだけで済みます。

インストール

npmを使用してライブラリをインストールします:

npm install jpostcode

使い方

基本的な使用例を以下に示します:

JavaScript

const { Jpostcode } = require('jpostcode');

// 郵便番号から住所を検索
const addresses = Jpostcode.find('0010000');

if (addresses.length > 0) {
  // 1つの郵便番号から複数の住所が見つかる場合があります
  for (const address of addresses) {
    console.log(`都道府県: ${address.prefecture} (${address.prefectureKana})`);
    console.log(`市区町村: ${address.city} (${address.cityKana})`);
    console.log(`町域: ${address.town} (${address.townKana})`);
    console.log(`郵便番号: ${address.zipCode}`);
  }
} else {
  console.log('住所が見つかりませんでした。');
}

TypeScript

import { Address, Jpostcode } from 'jpostcode';

// 郵便番号から住所を検索
const addresses:Address[] = Jpostcode.find('0010000');

if (addresses.length > 0) {
  // 1つの郵便番号から複数の住所が見つかる場合があります
  for (const address of addresses) {
    console.log(`都道府県: ${address.prefecture} (${address.prefectureKana})`);
    console.log(`市区町村: ${address.city} (${address.cityKana})`);
    console.log(`町域: ${address.town} (${address.townKana})`);
    console.log(`郵便番号: ${address.zipCode}`);
  }
} else {
  console.log('住所が見つかりませんでした。');
}

Node.js ESM

import { Jpostcode } from 'jpostcode';

const addresses = Jpostcode.find('0010000');
console.log(addresses[0]?.prefecture);

Webブラウザでの使用

Webアプリケーションでは、AJAX版またはBundle版のいずれかを使用できます:

AJAX版（ほとんどのケースで推奨）

<!-- AJAX版を読み込み -->
<script src="https://cdn.jsdelivr.net/npm/jpostcode@latest/dist/jpostcode-web.js"></script>

<script>
// データファイルのベースURLを設定（オプション、デフォルトは './data/json/'）
Jpostcode.setBaseUrl('https://your-cdn.com/jpostcode-data/');

// 住所を検索（Promiseを返します）
Jpostcode.find('1000001').then(addresses => {
  if (addresses.length > 0) {
    for (const address of addresses) {
      console.log(`都道府県: ${address.prefecture}`);
      console.log(`市区町村: ${address.city}`);
      console.log(`町域: ${address.town}`);
    }
  }
});
</script>

公式 Cloudflare CDN 版

ライブラリ本体と郵便番号データの両方を Cloudflare Pages から配信しています。npm を介さず、ホスティングも自前で用意せずに使えます:

<script src="https://jpostcode-js.pages.dev/dist/jpostcode-web.js"></script>

<script>
// データも同じ CDN から取得するように設定
Jpostcode.setBaseUrl('https://jpostcode-js.pages.dev/data/json/');

Jpostcode.find('1000001').then(addresses => {
  if (addresses.length > 0) {
    console.log(`都道府県: ${addresses[0].prefecture}`);
  }
});
</script>

• 上流の jpostcode-data の月次更新を反映して自動再配信
• 東京を含む Cloudflare エッジから低レイテンシで配信
• JSON データには s-maxage=2592000 (エッジ30日) / max-age=86400 (ブラウザ1日) のキャッシュヘッダ

Bundle版（全データ同梱）

<!-- Bundle版を読み込み（ファイルサイズは大きいですが、オフラインでも動作します） -->
<script src="https://cdn.jsdelivr.net/npm/jpostcode@latest/dist/jpostcode-web-bundle.js"></script>

<script>
// 住所を検索（同期処理）
const addresses = Jpostcode.find('1000001');
if (addresses.length > 0) {
  for (const address of addresses) {
    console.log(`都道府県: ${address.prefecture}`);
    console.log(`市区町村: ${address.city}`);
    console.log(`町域: ${address.town}`);
  }
}
</script>

機能

• 郵便番号による住所検索: 郵便番号を使用して詳細な住所情報を取得
• 存在しない郵便番号への対応: 郵便番号が存在しない場合は空の配列を返却
• Webブラウザ対応: WebアプリケーションのためのAJAX版とBundle版を提供
• TypeScript対応: 完全なTypeScript型定義を含む
• 常に最新の郵便番号データ: 毎月、上流データソース (jpostcode-data) の更新を検知して自動的に新バージョンを npm に公開。バージョン番号は MAJOR.MINOR.YYYYMM 形式で、データの取得時期がひと目で分かります

ビルドとテスト

プロジェクトをビルドするには:

npm run build

このコマンドで Node.js 用の CommonJS / ESM と、ブラウザ用の dist/jpostcode-web.js / dist/jpostcode-web-bundle.js を生成します。

テストを実行するには:

npm test

貢献

貢献を歓迎します！GitHubでissueを開くか、プルリクエストを送信してください。

謝辞

このプロジェクトは jpostcode-data ライブラリのデータを使用しています。このライブラリのメンテナと貢献者の皆様に感謝いたします。

GitHub Pagesデモ

このプロジェクトには、ライブラリの機能を日本語で紹介するGitHub Pagesデモサイトが含まれています。

ライブデモ

ライブデモは以下で公開されています: https://matzlika.github.io/jpostcode-js/

GitHub Pagesの設定

1. リポジトリのSettingsタブに移動
2. 左サイドバーの"Pages"に移動
3. "Source"で"GitHub Actions"を選択
4. mainブランチにプッシュすると自動的にデプロイされます

ローカル開発

デモサイトをローカルで実行するには:

# まずプロジェクトをビルド
npm run build

# データファイルへのシンボリックリンクを作成（まだ作成していない場合）
cd docs && ln -s ../jpostcode-data/data data && cd ..

# 静的ファイルサーバーでdocsディレクトリを配信
# 例: Pythonを使用する場合
python -m http.server 8000 --directory docs

# または Node.js http-serverを使用する場合
npx http-server docs -p 8000

その後、ブラウザで http://localhost:8000 を開きます。

ライセンス

このプロジェクトは MIT ライセンスの下で配布されています。詳細は LICENSE を参照してください。

本プロジェクトは jpostcode-data (Copyright 2023 SmartHR, Inc., MIT License) のデータを同梱しています。サードパーティ著作権表示については NOTICE を参照してください。

English version: README.en.md