对位置进行反向地理编码

欧洲经济区 (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 表单中捕获的位置组件时，您通常会使用结构化格式。

将所有其他参数作为网址参数传递，或者对于 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 进行身份验证。如需将 OAuth 与 Geocoding API 搭配使用，必须为 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 中的两个主要位置包含 types 数组：

    1. GeocodeResult.types：此数组表示结果的总体类型。可能的值来自“地点类型（新）”页面上的表 A 和表 B。
    2. GeocodeResult.addressComponents[].types：每个地址组成部分都有一个 types 数组，用于指明相应地址组成部分的类型。 这些值来自“地点类型（新）”页面上的地址类型和地址组成部分类型表格。

    反向地理编码器会在 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

    返回结果所用的语言。

    • 请参阅支持的语言列表。Google 会经常更新支持的语言，因此该列表可能并非详尽无遗。
    • 如果未提供 languageCode，则 API 默认为 en。如果您指定的语言代码无效，API 会返回 INVALID_ARGUMENT 错误。
    • 该 API 会尽力提供用户和当地人都能看懂的街道地址。为了实现这一目标，它会返回本地语言的街道地址，并在必要时根据首选语言将地址音译为用户可读的文字。所有其他地址均以首选语言返回。地址组成部分全部以同一种语言返回，该语言是从第一个组成部分中选择的。
    • 如果首选语言中没有相应名称，API 会使用最接近的匹配项。
    • 首选语言对 API 选择返回的结果集以及返回顺序有较小的影响。地理编码器会根据语言以不同的方式解读缩写，例如街道类型的缩写，或者在一种语言中有效但在另一种语言中无效的同义词。

  • regionCode

    地区代码，以 双字符 CLDR 代码值表示。没有默认值。大多数 CLDR 代码都与 ISO 3166-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

  • 类型

    一种或多种地址类型，以单独的查询参数形式指定。可能的值来自“地点类型（新）”页面上的地址类型和地址组成部分类型表。 如果您指定了多个 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

    创建响应字段掩码，以指定要在响应中返回的字段。使用网址参数 $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"
    },
    ...
  ]
}

    如需了解详情，请参阅选择要返回的字段。