場所をリバース ジオコーディングする

欧州経済領域（EEA）のデベロッパー

リバース ジオコーディングは、地図上の位置を人が読める住所に変換します。地図上の位置は、その場所の緯度と経度の座標で表します。

位置情報をリバース ジオコーディングすると、レスポンスには次の情報が含まれます。

この API は、最も詳細な番地まで含む住所から、区域、都市、郡、州などのより範囲の広い行政区画まで、さまざまなタイプの住所を返します。通常、最も正確な住所が最初の結果になります。特定のタイプの住所との一致を検索する場合は、types パラメータを使用します。

リバース ジオコーディング リクエスト

リバース ジオコーディング リクエストは HTTP GET リクエストです。場所は構造化されていない文字列として指定できます。

https://geocode.googleapis.com/v4/geocode/location/LATITUDE,LONGITUDE

または、クエリ パラメータで表される緯度と経度の座標の構造化されたセットとして指定します。

https://geocode.googleapis.com/v4/geocode/location?location.latitude=LATITUDE&location.longitude=LONGITUDE

通常、構造化形式は、HTML フォームでキャプチャされた位置情報コンポーネントを処理するときに使用します。

他のすべてのパラメータは、URL パラメータとして渡すか、API キーやフィールド マスクなどのパラメータの場合は、GET リクエストの一部としてヘッダーで渡します。次に例を示します。

非構造化された位置情報文字列を渡す

構造化されていない位置情報は、緯度と経度の座標をカンマ区切りで表した文字列としてフォーマットされます。

https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?key=API_KEY

または、curl コマンドで次の操作を行います。

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"

構造化された位置情報を渡す

構造化された位置情報は、location クエリ パラメータ（型: LatLng）を使用して指定します。LatLng オブジェクトを使用すると、緯度と経度を個別のクエリ パラメータとして指定できます。

https://geocode.googleapis.com/v4/geocode/location?location.latitude=37.4225508&location.longitude=-122.0846338&key=API_KEY

OAuth を使用してリクエストを行う

Geocoding API v4 は、認証に OAuth 2.0 をサポートしています。Geocoding API で OAuth を使用するには、OAuth トークンに正しいスコープが割り当てられている必要があります。Geocoding API は、リバース ジオコーディングで使用する次のスコープをサポートしています。

  • https://www.googleapis.com/auth/maps-platform.geocode — すべての Geocoding API メソッドで使用します。
  • https://www.googleapis.com/auth/maps-platform.geocode.location — リバース ジオコーディングでは GeocodeLocation と組み合わせてのみ使用します。

また、すべての Geocoding API メソッドに一般的な https://www.googleapis.com/auth/cloud-platform スコープを使用できます。このスコープは、すべてのメソッドへのアクセスを許可する一般的なスコープであるため、開発時には便利ですが、本番環境では使用できません。

詳細と例については、OAuth を使用するをご覧ください。

リバース ジオコーディングのレスポンス

リバース ジオコーディングは、次の情報を含む GeocodeLocationResponse オブジェクトを返します。

  • 場所を表す GeocodeResult オブジェクトの results 配列。

    Geocoding API のレスポンスには、GeocodeResult 内の次の 2 つの主要な場所に types 配列が含まれています。

    1. GeocodeResult.types: この配列は、結果の全体的なタイプを示します。指定できる値は、場所タイプ（新版）ページの表 A と表 B に記載されています。
    2. GeocodeResult.addressComponents[].types: 各住所コンポーネントには、住所の特定の部分のタイプを示す types 配列があります。これらの値は、[場所タイプ（新機能）] ページの住所タイプと住所コンポーネントのタイプの表から取得されます。

    リバース ジオコーダは、results 配列に複数の結果を返します。結果には、郵送先住所だけでなく、その場所の地理的な名称も含まれます。たとえば、シカゴ市のある地点のジオコーディングを行うと、ジオコーディングされる地点には番地、都市（シカゴ）、州（イリノイ）、国（米国）などのラベルが付きます。ジオコーダは、これらをすべて「住所」と認識します。リバース ジオコーダは、これらのタイプを有効な結果として返します。

  • PlusCode 型の plusCode フィールドには、リクエストの緯度と経度を最もよく近似するプラスコードが含まれます。また、results 配列の各要素にはプラスコードが含まれています。デコードされたプラスコードとリクエスト ポイントの距離が 10 メートル未満である。

    注: API は常にプラスコードを返すわけではありません。

完全な JSON オブジェクトは次の形式です。

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "placeId": "ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "location": {
        "latitude": 37.422588300000008,
        "longitude": -122.0846489
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.421239319708512,
          "longitude": -122.0859978802915
        },
        "high": {
          "latitude": 37.423937280291511,
          "longitude": -122.08329991970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        }
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCW83+PM",
        "compoundCode": "CW83+PM Mountain View, CA, USA"
      }
    },
    {
      "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "location": {
        "latitude": 37.4220541,
        "longitude": -122.08532419999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4207051197085,
          "longitude": -122.08667318029148
        },
        "high": {
          "latitude": 37.423403080291493,
          "longitude": -122.08397521970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        }
      ],
      "types": [
        "establishment",
        "point_of_interest"
      ],
      "plusCode": {
        "globalCode": "849VCWC7+RV",
        "compoundCode": "CWC7+RV Mountain View, CA, USA"
      }
    },
   ...
  ],
  "plusCode": {
    "globalCode": "849VCWF8+24H",
    "compoundCode": "CWF8+24H Mountain View, CA, USA"
  }
}

必須パラメータ

  • ロケーション

    人が読める形式の最も近い住所を取得する場所を指定する緯度と経度の座標。

オプション パラメータ

  • languageCode

    結果を返す言語。

    • サポートされている言語の一覧をご覧ください。サポート対象の言語は頻繁に更新されるため、このリストで網羅されていない場合があります。
    • languageCode が指定されていない場合、API はデフォルトで en になります。無効な言語コードを指定すると、API は INVALID_ARGUMENT エラーを返します。
    • API は、ユーザーと地元住民の両方が読める番地を可能な限り提供します。この目標を達成するため、優先言語を考慮し、必要に応じてユーザーが読める文字に音訳して、現地の言語で住所を返します。その他の住所はすべて、優先言語で返されます。住所コンポーネントはすべて同じ言語で返されます。この言語は最初のコンポーネントから選択されます。
    • 優先言語で名前が使用できない場合、API は最も近い一致を使用します。
    • 優先言語は、API が返す結果のセットと、それらが返される順序にわずかな影響を与えます。ジオコーダーは、言語によって略語（通りの種類の略語や、ある言語では有効でも別の言語では有効でない同義語など）を異なる方法で解釈します。

  • regionCode

    2 文字の CLDR コード値で表される地域コード。デフォルト値はありません。ほとんどの CLDR コードは ISO 3166-1 コードと同一です。

    住所のジオコーディング（フォワード ジオコーディング）を行う場合、このパラメータは、サービスから返される結果を特定の地域に制限するものではありませんが、その地域を優先して結果を返すように影響を与えることができます。位置情報または場所のジオコーディング、リバース ジオコーディング、場所のジオコーディングを行う際に、このパラメータを使用して住所の形式を指定できます。いずれの場合も、このパラメータは適用される法律に基づいて結果に影響を与える可能性があります。

  • 粒度

    Granularity で定義されている 1 つ以上の位置情報の粒度。別々のクエリ パラメータとして指定します。複数の granularity パラメータを指定すると、API は、いずれかの粒度に一致するすべてのアドレスを返します。

    granularity パラメータは、検索を指定した場所の粒度に制限するものではありません。むしろ、granularity は検索後のフィルタとして機能します。API は、指定された location のすべての結果を取得し、指定された場所の粒度に一致しない結果を破棄します。

    types と granularity の両方を指定すると、両方に一致する結果のみが返されます。次に例を示します。

    https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?granularity=ROOFTOP&granularity=GEOMETRIC_CENTER&key=API_KEY

  • タイプ

    1 つ以上のアドレスタイプ。個別のクエリ パラメータとして指定します。使用可能な値は、プレイスタイプ（新規）ページの住所のタイプと住所コンポーネントのタイプの表から取得されます。複数の types パラメータを指定すると、API は、いずれかのタイプに一致するすべてのアドレスを返します。

    types パラメータは、検索対象を特定の住所タイプに制限しません。むしろ、types は検索後のフィルタとして機能します。API は、指定された場所のすべての結果を取得し、指定された住所タイプに一致しない結果を破棄します。

    types と granularity の両方を指定すると、API は両方に一致する結果のみを返します。次に例を示します。

    https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2&types=locality&key=API_KEY

  • FieldMask

    レスポンス フィールド マスクを作成して、レスポンスで返すフィールドを指定します。レスポンス フィールド マスクをメソッドに渡すには、URL パラメータ $fields または fields を使用するか、HTTP ヘッダー X-Goog-FieldMask を使用します。たとえば、次のリクエストはレスポンスの placeID フィールドのみを返します。

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"
    レスポンスは次のとおりです。
    {
  "results": [
    {
      "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE"
    },
    {
      "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g"
    },
    {
      "placeId": "ChIJ1yjFJ1-7j4ARG_RVqFD1h7k"
    },
    {
      "placeId": "ChIJ09H2YwK6j4ARoF7qfCBxhB8"
    },
    ...
  ]
}

    詳細については、返すフィールドの選択をご覧ください。