地点地理编码

欧洲经济区 (EEA) 开发者

地点地理编码功能可让您通过地点 ID 检索地址。

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

发出地点地理编码请求

地点地理编码请求是一种 HTTP GET 请求，其格式如下：

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

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

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

https://geocode.googleapis.com/v4beta/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/v4beta/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 搭配使用，用于地点地理编码。

此外，您还可以为所有 Geocoding API 端点使用常规 https://www.googleapis.com/auth/cloud-platform 范围。该范围在开发期间很有用，但在生产期间则不然，因为这是一个通用范围，允许访问所有端点。

如需了解详情和示例，请参阅使用 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 搭配使用。例如，您可以使用 Roads API 返回的 placeID 来获取贴合点的地址。如需详细了解地点 ID，请参阅地点 ID。

可选参数

  • languageCode

    返回结果所用的语言。

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

  • regionCode

    地区代码，以 双字符 CLDR 代码值表示。没有默认值。大多数 CLDR 代码都与 ISO 3166-1 代码完全一致。

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