对地点进行地理编码

欧洲经济区 (EEA) 开发者

地点地理编码可让您从地点 ID检索地址。

地点 ID 可唯一标识 Google Places 数据库中和 Google 地图上的地点。对地址进行地理编码时，您可以检索地点 ID 。您还可以从许多其他 API（例如 地点详情（新）、 文本搜索（新）和 附近搜索 （新））检索地点 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 对应的地点。

完整的 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 默认使用 en。如果您指定了无效的语言代码，API 会返回 INVALID_ARGUMENT 错误。
    • API 会尽力提供用户和当地人都能看懂的街道地址。为实现这一目标，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"
}

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