use-postal-jp

郵便番号を住所に変換するReactカスタムフックです。住所データを内部に持たず、APIで住所変換するため軽量なパッケージになっています。

Install

// npm
npm install --save use-postal-jp

// yarn
yarn add use-postal-jp

DEMO

https://use-postal-jp.vercel.app/

Usage

import React, { useEffect, useState } from 'react'
import { usePostalJp } from 'use-postal-jp'

const App = () => {
  const [value, setValue] = useState('')
  const [address, loading, error] = usePostalJp(value, value.length >= 7)

  return (
    <div>
      <input type='text' onChange={(e) => setValue(e.target.value)} />
      {!loading &&
        <>
          <p>prefectureCode: {address.prefectureCode && address.prefectureCode}</p>
          <p>prefecture: {address.prefecture && address.prefecture}</p>
          <p>address1: {address.address1 && address.address1}</p>
          <p>address2: {address.address2 && address.address2}</p>
          <p>address3: {address.address3 && address.address3}</p>
          <p>address4: {address.address4 && address.address4}</p>
          <p>error: {error && error.message}</p>
        </>
      }
    </div>
  )
}

usePostalJp

const [address, loading, error] = usePostalJp(postalCode, ready, { url, parse })

Args

usePostalJp(postalCode, ready, option)

• postalCode: string (必須)
  • 郵便番号の文字列
  • ハイフンあり('100-0001')、全角('１００ー０００１') でもOK
• ready: boolean (必須)
  • true をわたすと、APIリクエストが行われる
• option: object (任意)
  • madefor/postal-code-api 以外の独自のエンドポイントを使用する場合に使用
  • 詳細は後述 (カスタムエンドポイントを使用する場合)

Returns

const [address, loading, error] = usePostalJp(...)

• address: Address | null

type Adress = {
  prefectureCode: string; // 都道府県コード
  prefecture: string; // 都道府県
  address1: string; // 市区町村
  address2: string; // 市区町村配下
  address3: stging; // 更に詳細情報
  address4: string; // 建物名など
}

• loading: boolean
  • API通信中は true になる
• error: Error | null
  • 郵便番号の桁不足や、存在しない郵便番号でAPIが叩かれるなどしたときに、エラーオブジェクトが返却される
  • 正常であれば null

カスタムエンドポイントを使用する場合

// エンドポイントを作成する関数: 前方3桁、後方4桁の半角郵便番号数字が配列で引数に渡される
const url = ([code1, code2]: [string, string]) => `https://your.api.com/api?postal_code=${code1}-${code1}`
// エンドポイントからのレスポンスをパースする関数: 返り値が直接 address となる
const parse = (res: YourResBodyObject) => ({
  prefecture: res[0].prefecture_name,
  city: res[0].city_name,
  town: res[0].town_name
})

// address: { prefecture: string; city: string; town: string } | null
const [address, loading, error] = usePostalJp(postalCode, ready, { url, parse })

住所検索API

本プロジェクトでは madefor/postal-code-api の住所検索APIを使用させていただいております。 オーナー様及びコントリビューターの方々に感謝申し上げます。

License

MIT © aiji42