Address Search API | PostcodeJP Docs

API Keyを準備する

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

利用用途に合う制限を設定する

Browserから使うAPI KeyにはHTTP Referer制限、Serverから使うAPI KeyにはIP/CIDR制限を設定してください。

開発環境と本番環境、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

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

直接呼び出す場合はAPI KeyをURLへ含めない

Address Search APIを直接呼び出す場合は、ブラウザ履歴やアクセスログへの混入を避けるため、認証情報をapikey headerで送信してください。ブラウザ利用ではHTTP Referer制限、サーバー利用ではIP/CIDR制限を設定します。

Query parameters

Parameter	Type	Default	Contract
filter	string	任意	field・operator・valueで検索条件を指定
limit	integer	10	1〜50
cursor	string	任意	直前のレスポンスが返したopaque cursor
callback	string	任意	JSONP callback名。最大1,000文字
fields	string	全field	返却fieldをカンマ区切りで指定
sort	string	default order	+field / -field / fieldをカンマ区切りで指定

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

Response

200 response — structural example

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

Key	Type	Meaning
`data`	array	現在のpageに含まれる検索結果
`size`	number	現在のpageの結果件数。総hit数ではありません
`limit`	number	指定または適用されたpage limit
`hasNext`	boolean	次のpageがあるか
`hasPrev`	boolean	前のpageがあるか
`nextCursor`	string / absent	次page用cursor。次pageがない場合は省略
`prevCursor`	string / absent	前page用cursor。前pageがない場合は省略
`version`	string	レスポンスに使用されたdataset version

Partial fields

fieldsを指定した場合、各resultには指定したfieldだけが返り得ます。たとえばfields=prefではprefだけが返り、postcodeは自動追加されません。

Response fields

Field	Type	Meaning
prefCode	string	都道府県コード
cityCode	string	市区町村コード
postcode	string	郵便番号
oldPostcode	string	旧郵便番号
pref / city / town / office	string	住所・事業所名の各要素
allAddress	string	住所要素を連結した表記
hiragana	object	pref / city / town / office / allAddress
halfWidthKana	object	pref / city / town / office / allAddress
fullWidthKana	object	pref / city / town / office / allAddress
english	object	pref / city / town / office / allAddress。データがある要素のみ
generalPostcode	boolean	一般郵便番号かどうか
officePostcode	boolean	事業所郵便番号かどうか
location	object	代表点。確定できない場合はnullまたは省略

文字列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は提供元の公開時期と品質確認に合わせて更新されます。固定の日次時刻や更新間隔は保証しません。