# Jpostcode

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

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

## インストール

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

```bash
npm install jpostcode
```

## 使い方

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

### JavaScript

```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

```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

```javascript
import { Jpostcode } from 'jpostcode';

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

### Webブラウザでの使用

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

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

```html
<!-- 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 を介さず、ホスティングも自前で用意せずに使えます:

```html
<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](https://github.com/kufu/jpostcode-data) の月次更新を反映して自動再配信
- 東京を含む Cloudflare エッジから低レイテンシで配信
- JSON データには `s-maxage=2592000` (エッジ30日) / `max-age=86400` (ブラウザ1日) のキャッシュヘッダ

#### Bundle版（全データ同梱）

```html
<!-- 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](https://github.com/kufu/jpostcode-data)) の更新を検知して自動的に新バージョンを npm に公開。バージョン番号は `MAJOR.MINOR.YYYYMM` 形式で、データの取得時期がひと目で分かります

## ビルドとテスト

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

```bash
npm run build
```

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

テストを実行するには:

```bash
npm test
```

## 貢献

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

## 謝辞

このプロジェクトは [jpostcode-data](https://github.com/kufu/jpostcode-data) ライブラリのデータを使用しています。このライブラリのメンテナと貢献者の皆様に感謝いたします。

## GitHub Pagesデモ

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

### ライブデモ

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

### GitHub Pagesの設定

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

### ローカル開発

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

```bash
# まずプロジェクトをビルド
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](LICENSE) を参照してください。

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

---

**English version**: [README.en.md](README.en.md)