Address Search API

API Keyを準備する

1. PostcodeJP管理画面へログインします。
2. メニューの「APIキー」を開き、「作成」からAPI Keyを作成します。
3. 利用環境に合わせて「制限」を設定します。Browserでは「HTTP リファラー」、Serverでは「IP アドレス」にIPまたはCIDRを登録します。
4. 作成したAPI Keyをrequestのapikey headerへ設定します。

開発環境と本番環境、BrowserとServerなど、用途別にAPI Keyを分けると管理しやすくなります。不要になったAPI Keyは管理画面の「APIキー」から削除してください。

Quick start

Base URL

https://apis.postcode-jp.com/api/v6

Endpoint

GET /postcodes

Authentication

apikey header

Response

application/json

curl --get 'https://apis.postcode-jp.com/api/v6/postcodes' \
  --header 'apikey: YOUR_API_KEY' \
  --data-urlencode 'filter=postcode==1000001' \
  --data-urlencode 'limit=1'

例: 配送・サービス提供エリアを判定する

Address Search APIから取得した都道府県・市区町村・町域などを、自社の配送対象・訪問対象などのエリア条件と照合できます。

1. 入力された郵便番号でAddress Search APIを検索します。
2. pref・city・必要に応じてtownを取得します。
3. 同じ郵便番号で複数の住所候補が返る場合を考慮し、候補を自社の提供エリア条件またはマスタと照合します。

const serviceAreas = new Set([
  "東京都千代田区",
  "東京都中央区"
]);

const params = new URLSearchParams({
  filter: "postcode==1000001",
  limit: "50",
  fields: "pref,city,town"
});

const response = await fetch(
  `https://apis.postcode-jp.com/api/v6/postcodes?${params}`,
  { headers: { apikey: process.env.POSTCODEJP_API_KEY! } }
);

if (!response.ok) throw new Error(`PostcodeJP: ${response.status}`);

const { data } = await response.json();
const serviceAvailable = data.some(({ pref, city }) =>
  serviceAreas.has(`${pref}${city}`)
);

Query parameters

filterの構文と公開fieldはFilterリファレンスを参照してください。

Response

{
  "data": [
    {
      "postcode": "1000001",
      "pref": "東京都",
      "city": "千代田区",
      "english": {
        "pref": "Tokyo",
        "city": "Chiyoda-ku"
      }
    }
  ],
  "size": 1,
  "limit": 1,
  "hasNext": false,
  "hasPrev": false,
  "version": "dataset-version"
}

Response fields

文字列fieldは、対象datasetに値が存在しない場合があります。English fieldを含め、すべてのresultですべての値が存在することは保証しません。

Cursor paginationとsort

• limitのdefaultは10、範囲は1〜50です。
• nextCursorまたはprevCursorを、そのまま次のrequestのcursorへ渡します。
• cursor取得後にfilterやsortを変更しないでください。
• sortは+fieldまたは無印で昇順、-fieldで降順です。複数fieldはカンマで区切ります。
• English fieldもsortに利用できます。

位置情報

locationは住所粒度に対応する代表点です。JSONではlatitudeが緯度、longitudeが経度です。座標系はWGS84（SRID 4326）です。

利用できる住所粒度の代表点を使用し、確定できない場合は同一郵便番号や市区町村など、より広い粒度の代表点へフォールバックします。位置を確定できない場合はnullまたはfield自体を省略します。

Dataset version

clientは通常、current datasetを自動的に利用します。レスポンスのversionを記録すると、そのレスポンスに使われたdatasetを識別できます。

datasetは提供元の公開時期と品質確認に合わせて更新されます。固定の日次時刻や更新間隔は保証しません。