ジオコーディング

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

📬 リクエスト

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」を返却しますのでご注意ください
ジオコーディング精度向上にあたっては、以下の内容を満たすように住所文字列を修正してください

住所文字列の要件

必須/推奨	要件
必須	ジオコーディング対象の文字列が、最新の正しい住所情報であること（英数字/漢数字、全角/半角の両方に対応しています）
必須	ジオコーディング対象の文字列に、国名を含めないこと
必須	ジオコーディング対象の文字列に、郵便番号を含めないこと
必須	ジオコーディング対象の文字列は、1. 都道府県, 2. 市区郡, 3. 町名番地の順で設定すること
必須	ジオコーディング対象の文字列に、非対応のハイフンを含めないこと
推奨	ジオコーディング対象の文字列に、ビル名や建物名を含めないこと

対応しているハイフン

文字	UTF-8	Unicode	説明
`-`	2D	U+002D	ASCIIのハイフン
`‐`	E28090	U+2010	別のハイフン
`―`	E28095	U+2015	全角のダッシュ
`−`	E28892	U+2212	全角のマイナス
`ー`	E383BC	U+30FC	全角の長音

非対応のハイフン

文字	UTF-8	Unicode	説明
`‑`	E28091	U+2011	改行しないハイフン
`–`	E28093	U+2013	ENダッシュ
`—`	E28094	U+2014	EMダッシュ
`ｰ`	EFBDB0	U+FF70	半角カナの長音

📚 参考資料

なし