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

欧州経済領域（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"

構造化された場所を渡す

LatLng タイプの location クエリ パラメータを使用して、構造化されたロケーションを指定します。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: この配列は、 結果の全体的なタイプを示します。指定できる値は、Places API で使用される場所タイプから取得されます。詳しくは、場所のタイプ表 A と表 B をご覧ください。
    2. GeocodeResult.addressComponents[].types: 各住所コンポーネントには、住所の特定の部分のタイプを示す types 配列があります。これらの値は、Places API で使用される住所のタイプと住所コンポーネントのタイプの表から取得されます。

    リバース ジオコーダは、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 はデフォルトで、その場所の現地の言語と文字を使用します。無効な言語コードを指定すると、API は INVALID_ARGUMENT エラーを返します。
    • API は、ユーザーと現地の人の両方が読み取れる番地を提供するように最善を尽くします。この目標を達成するため、住所は現地語で返されます。必要に応じて、ユーザーが読み取れる文字に変換され、優先言語が考慮されます。その他の住所はすべて、優先言語で返されます。住所コンポーネントはすべて同じ言語で返されます。この言語は、最初のコンポーネントから選択されます。
    • 優先言語で名前が利用できない場合、API は最も近い一致を使用します。
    • 優先言語は、API が返す結果のセットと、それらが返される順序にわずかに影響します。ジオコーダは、言語に応じて略語を異なる方法で解釈します。たとえば、道路タイプの略語や、ある言語では有効でも別の言語では有効でない類義語などです。

  • regionCode

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

    住所をジオコーディング（前方ジオコーディング）する場合、このパラメータは、サービスから指定された地域への結果に影響を与えますが、完全に制限するわけではありません。ロケーションまたは場所をジオコーディングする場合（リバース ジオコーディングまたは場所のジオコーディング）、このパラメータを使用して住所をフォーマットできます。いずれの場合も、このパラメータは適用される法律に基づいて結果に影響する可能性があります。

  • 粒度

    1 つ以上のロケーションの粒度。Granularity で定義されているように、個別のクエリ パラメータとして指定します。複数の 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 パラメータを指定すると、いずれかのタイプに一致するすべてのアドレスが返されます。

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

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