Address Parser

Preview

Address Parserは正式版前のPreviewです。schemaやbehaviorが変更される可能性があるため、production integrationでは変更を確認し、union typeと未知fieldを安全に扱ってください。

API Keyを準備する

Address Parser専用のAPI Keyは必要ありません。Address Search APIと共通のAPI Keyをapikey headerへ設定します。

作成と利用元の制限については、API Keyの準備方法を確認してください。

Request

Endpoint: POST https://apis.postcode-jp.com/api/v6/parse
Authentication: apikey header
Content-Type: application/json
Body: {"address":"..."}

cURL

curl 'https://apis.postcode-jp.com/api/v6/parse' \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"address":"東京都千代田区千代田1-1"}'

Success response

HTTP 200では、top-levelにjapanese、english、metaを返します。

Structural example

{
  "japanese": {
    "prefecture": "東京都",
    "city": "千代田区"
  },
  "english": {
    "prefecture": "Tokyo",
    "city": "Chiyoda-ku"
  },
  "meta": {
    "input": "...",
    "formatted_address": "...",
    "postal_code": ["1000001"],
    "score": 0.95,
    "score_detail": {},
    "warnings": [],
    "notices": []
  }
}

Address components

解析できた範囲で、prefecture、county、city、ward、district、koaza、street、chome、block、house_num、building、roomなどを返します。すべてのfieldが常に存在するとは限りません。

`meta.postal_code`

public typeは次のunionです。

TypeScript

type ParserPostalCode = string | string[] | null;

値の形状は入力と解析結果によって異なり得ます。単一stringだけ、またはarrayだけを仮定しないでください。

Application errors

406 — parse failure

406 response

{
  "detail": {
    "code": "PARSE_FAILURE",
    "httpStatusCode": 406,
    "message": "..."
  }
}

detailはobjectです。human-readable messageの完全一致をstable contractとして扱わないでください。

422 — request validation

422 response

{
  "detail": [
    {
      "input": {},
      "loc": ["body", "address"],
      "msg": "...",
      "type": "missing"
    }
  ]
}

required addressがない場合などは、framework validationのdetail arrayを返します。406のobject schemaとは別です。

認証・利用制限のerrors

401、403、429のbodyは、applicationの406/422 bodyと同じschemaとは限りません。HTTP statusを先に判定してください。

401: API Keyを確認
403: Referer/IP/権限/利用範囲を確認
429: Retry-Afterの秒数を待ち、bounded backoffとjitterを使用

Preview limitations

誤記や表記揺れを必ず補正できることは保証しません。
未知の住所要素や解析不能な末尾がwarningsへ反映される場合があります。
住所の真正性、配送可能性、建物入口の位置は判定しません。