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

欧州経済領域（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 スコープを使用することもできます。このスコープは、すべてのメソッドへのアクセスを許可する汎用スコープであるため、開発時には便利ですが、本番環境では使用しないでください。

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

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

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

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

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

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

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

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

    注: API は常に Plus Code を返すとは限りません。

完全な 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 の両方を指定すると、API は両方に一致する結果のみを返します。次に例を示します。

    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"
    },
    ...
  ]
}

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