ジオコーディング

リクエストボディで指定された住所リストを経緯度形式に変換して返却する

📬 リクエスト

POST https://engine-prod-je-apim.azure-api.net/connect/api/v1/geocode

リクエストヘッダ

キー	値
Content-Type	`application/json`
X-API-Key	認証用のAPIキー

リクエストボディ

キー	形式	必須	説明	値の例
requests	requestオブジェクトの配列	YES	経緯度変換対象の住所リスト（最大100件）	`[ { "id": "address-001", "address": "東京都千代田区丸の内１丁目４−１" }, ... ]`

requestオブジェクト

キー	形式	必須	説明	値の例
id	文字列	YES	`requests`の配列内で一意となる任意の文字列（最大255文字）	`address-001`
address	文字列	YES	住所文字列（最大512文字）	`東京都千代田区丸の内１丁目４−１`

リクエストボディのサンプル

{
  "requests": [
    {
      "id": "address-001",
      "address": "東京都千代田区丸の内１丁目４−１"
    },
    {
      "id": "address-002",
      "address": "存在しない住所文字列"
    }
  ]
}

✨ 成功レスポンス

ステータスコード

200 : OK

レスポンスヘッダ

キー	値
Content-Type	`application/json`

レスポンスボディ

フィールド	形式	必須	説明	値の例
results	ジオコーディング結果オブジェクトの配列	YES	ジオコーディング結果の配列	`[ { "id": "address-001", "requestAddress": "東京都千代田区丸の内１丁目４−１", "status": "SUCCEEDED", "result": { ... } }, ... ]`

ジオコーディング結果オブジェクト

フィールド	形式	必須	説明	値の例
id	文字列	YES	リクエスト時に指定されたID	`address-001`
requestAddress	文字列	YES	リクエスト時に指定された住所文字列	`東京都千代田区丸の内１丁目４−１`
status	`SUCCEEDED`（成功） `FAILED`（失敗）	YES	結果ステータス	`SUCCEEDED`
result	ジオコーディング変換結果オブジェクト	NO	住所文字列の変換結果（「status」フィールドが`FAILED`の場合はnull）	`null`
error	文字列	NO	エラー内容（「status」フィールドが`SUCCEEDED`の場合はnull）	`Status:-100`

ジオコーディング変換結果オブジェクト

フィールド	形式	必須	説明	値の例
x	数値（小数点以下最大8桁）	YES	経度	`139.764414`
y	数値（小数点以下最大8桁）	YES	緯度	`35.683961`
matchingLv	`1`（都道府県） `2`（特別区、市区郡） `3`（町、大字） `4`（丁目・字） `5`（地番街区符号、枝番住居番号）	YES	住所のどの要素のレベルまでマッチしたかを示す数値	`4`
responseAddress	文字列	YES	マッチした要素のレベルまでの正規化された住所文字列	`東京都千代田区丸の内１丁目4番`

レスポンスボディのサンプル

{
  "results": [
    {
      "id": "address-001",
      "requestAddress": "東京都千代田区丸の内１丁目４−１",
      "status": "SUCCEEDED",
      "result": {
        "x": 139.764414,
        "y": 35.683961,
        "matchingLv": 4,
        "responseAddress": "東京都千代田区丸の内１丁目4番"
      }
    },
    {
      "id": "address-002",
      "requestAddress": "存在しない住所文字列",
      "status": "FAILED",
      "result": null,
      "error": "Status:-100"
    }
  ]
}

💥 失敗レスポンス

HTTPコード	考えられる原因
`400`: Bad Request	リクエストボディの形式が不正 / 「id」の重複 / 100件以上のリクエストを指定
`401`: Unauthorized	リクエストヘッダに「X-API-Key」の値がない / 「X-API-Key」の値が不正
`429`: Too Many Requests	レート制限を超過（リクエストが短時間に大量に送信された場合など）レスポンスヘッダの「Retry-After」に待機秒数を設定するので、指定秒数経過後に再送してください

💬 具体的な要求事項

リクエストの配列順序とレスポンスの配列順序は一致しません。必ず、「id」フィールドを用いた突き合わせを行ってください
すべてのリクエストがジオコーディングできない場合も成功レスポンスとして「200 : OK」を返却しますのでご注意ください
ジオコーディング精度向上にあたっては、マッチングレベルの向上施策も合わせてご確認ください

📚 参考資料

マッチングレベルの向上施策