对地点进行地理编码

欧洲经济区 (EEA) 开发者

通过地点地理编码，您可以从地点 ID检索地址。

地点 ID 可唯一标识 Google Places 数据库中和 Google 地图上的地点。对地址进行地理编码 时，您可以检索地点 ID。您还可以从许多其他 API（例如 地点详情 (New)、 文本搜索 (New)和 附近搜索 (New)）检索地点 ID。

地点地理编码请求

地点地理编码 请求 是采用以下形式的 HTTP GET 请求：

https://geocode.googleapis.com/v4/geocode/places/PLACE_ID

其中，PLACE_ID 包含感兴趣的位置的地点 ID。

将所有其他参数作为网址参数传递，或者对于 API 密钥或字段掩码等参数，在标头中作为 GET 请求的一部分传递。例如：

https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?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/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"

使用 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.place - 仅与 GeocodePlace 搭配使用，用于地点地理编码。

此外，您还可以将通用的 https://www.googleapis.com/auth/cloud-platform 范围用于所有 Geocoding API 方法。此范围在开发期间非常有用，但在生产环境中则不适用，因为它是通用范围，允许访问所有方法。

如需了解详情和示例，请参阅使用 OAuth。

地点地理编码响应

地点地理编码会返回一个 GeocodeResult 对象，该对象表示与地点 ID 对应的地点。

Geocoding API 响应在 GeocodeResult 中的两个主要位置包含 types 数组：

  1. GeocodeResult.types：此数组表示结果的总体类型。可能的值来自 Places API 使用的地点类型。如需了解详情，请参阅地点类型表 A 和表 B。
  2. GeocodeResult.addressComponents[].types：每个地址组成部分都有一个 types 数组，用于表示地址中该特定部分的类型。 这些值来自 地址类型和地址组成部分 类型表，Places API 使用该表。

完整的 JSON 对象采用以下形式：

{
  "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "location": {
    "latitude": 37.4220541,
    "longitude": -122.08532419999999
  },
  "granularity": "ROOFTOP",
  "viewport": {
    "low": {
      "latitude": 37.4209489697085,
      "longitude": -122.08846930000001
    },
    "high": {
      "latitude": 37.4236469302915,
      "longitude": -122.0829156
    }
  },
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
  "postalAddress": {
    "regionCode": "US",
    "languageCode": "en",
    "postalCode": "94043",
    "administrativeArea": "CA",
    "locality": "Mountain View",
    "addressLines": [
      "1600 Amphitheatre Pkwy"
    ]
  },
  "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"
  ]
}

必需参数

  • place - 您要用来获取人类可读地址的地点 ID。地点 ID 是唯一 标识符，可以与其他 Google API 搭配使用。例如，您可以 提供 placeID 返回的 Roads API 来获取对应点的地址。如需详细了解地点 ID，请参阅地点 ID。

可选参数

  • languageCode

    返回结果所用的语言。

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

  • regionCode

    区域代码，采用 双字符 CLDR 代码值。没有默认值。大多数 CLDR 代码都与 ISO 3166-1 代码相同。

    对地址进行地理编码（即正向地理编码）时，此参数可以影响但不会 完全限制服务返回指定区域的结果。对位置或地点进行地理编码（即反向地理编码或地点地理编码）时，此参数可用于设置地址格式。在所有情况下，此参数都可能会根据适用法律影响结果。

  • FieldMask

    创建响应字段掩码，以指定要在响应中返回的字段。使用网址参数 $fields 或 fields，或者使用 HTTP 标头 X-Goog-FieldMask，将响应字段掩码传递给方法。例如，以下请求将仅返回响应的 formattedAddress 字段。

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: formattedAddress' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    响应为： 
    {
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA"
}

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