japanpostcode

日本郵便公式 郵便番号・デジタルアドレスAPIのラッパーライブラリです。

APIの利用者登録について

公式サイトにて下記を行なってください。

1. ゆうID登録
2. APIの利用者アカウント登録
3. APIキー/シークレットキーの発行
4. 実行環境のホスト名(IPアドレス)を登録

このライブラリでは3,4を利用します。

特徴

• 郵便局公式APIを使用
• TypeScript対応
• Node.js 18+ と Bun の両方で動作
• 環境変数による認証情報の設定に対応

インストール

npm install japanpostcode
# または
bun add japanpostcode

使用方法

初期化時のパラメータは環境変数 JAPANPOST_CLIENT_ID、JAPANPOST_SECRET_KEY、X_FORWARDED_FOR を設定することで、省略できます。

import { JapanPostCodeClient } from 'japanpostcode';

// クライアントの初期化
const client = new JapanPostCodeClient({
  client_id: 'your-client-id',
  secret_key: 'your-secret-key',
  xForwardedFor: 'your-forwarded-for-value',
});

// 郵便番号から住所を取得
try {
  const result = await client.getAddress('1000004');
  console.log(result.addresses);
  // [
  //   {
  //     zip_code: '1000004',
  //     pref_name: '東京都',
  //     city_name: '千代田区',
  //     town_name: '大手町',
  //     ...
  //   }
  // ]
} catch (error) {
  console.error('Error:', error);
}

開発

# ビルド
npm run build

# 単体テストを実行（モックデータを使用）
npm test
# または
bun test

ターミナルでの動作確認

このライブラリをターミナルで動作確認するには、以下の手順を実行してください。

1. 環境変数の設定

環境変数に認証情報とX-Forwarded-Forを設定します：

export JAPANPOST_CLIENT_ID='your-client-id'
export JAPANPOST_SECRET_KEY='your-secret-key'
export X_FORWARDED_FOR='your-forwarded-for-value'

または、.envファイルを作成して設定することもできます（Bunを使用する場合、自動的に読み込まれます）。

2. テストスクリプトの実行

任意の郵便番号を指定できます。

npm run test:terminal 1000004