从地理编码 v3 迁移到 v4

欧洲经济区 (EEA) 开发者

如果您的账单邮寄地址在欧洲经济区，自 2025 年 7 月 8 日起，您在使用服务时需遵守 Google Maps Platform EEA 服务条款。具体功能因区域而异。 了解详情。

Geocoding API v4 引入了多个新端点，用于替换 API v3 中的功能。本指南将介绍如何迁移应用以使用新的 v4 端点。

您可以将现有 API 密钥与新的 v4 端点搭配使用。不过，如果您已针对 API 的 v3 版本请求提高配额，则必须针对新的 v4 API 请求提高配额。JavaScript 用户没有迁移途径。

注意：在预览期间，Geocoding API v4 方法的每秒查询次数 (QPS) 限制为 25。如需了解如何申请提高配额，请参阅 查看和管理配额，然后选择 Geocoding API 作为服务。

从 v3 正向地理编码迁移

如果您使用地理编码对地址进行地理编码，则应迁移到接受 GET 请求的 v4 对地址进行地理编码端点。

v4 API 更改了多个参数的名称、结构和支持。我们强烈建议您使用字段掩码来指定您希望在响应中返回的字段。

警告： 在所有 v4 端点中，字段名称均采用小驼峰式命名法（例如 addressComponents），这与 v3 端点（采用蛇形命名法，例如 address_components）不同。与 v3 一样，RPC 响应在 v4 中继续使用蛇形命名法。

请求参数变更

v3 参数	v4 参数	备注
address、components	address	非结构化地址（v3 address）现在通过网址路径传递。组件过滤条件 (v3 components) 现在以 address.* 查询参数的形式传递。
bounds	locationBias.rectangle	已重命名；结构已更改为对象。
language	languageCode	已重命名。
region	regionCode	已重命名。
extra_computations	已移除

响应字段变更

v3 字段	v4 字段	备注
status、error_message	已移除	v4 使用 HTTP 状态代码和错误正文。
results.address_components.long_name/results.address_components.short_name	results.addressComponents.longText/results.addressComponents.shortText	已重命名。
results.geometry.location_type	results.granularity	已重命名。
results.geometry.location	results.location	字段名称：lat/lng -> latitude/longitude。
results.geometry.viewport	results.viewport	字段名称：northeast/southwest -> high/low。
results.postcode_localities	results.postalCodeLocalities	已重命名。现在，针对一个或多个地区返回（需要 v3 >1）。
results.partial_match	已移除
全新设计	results.addressComponents.languageCode	特定地址组成部分的语言。
全新设计	results.bounds	使用 high/low 的显式边界。
全新设计	results.place	地点的资源名称。
全新设计	results.postalAddress	结构化 PostalAddress 对象。

从 v3 反向地理编码迁移

如果您使用反向地理编码将坐标转换为地址，则应迁移到 v4 对位置进行反向地理编码端点，该端点接受 GET 请求。

v4 API 更改了多个参数的名称、结构和支持。我们强烈建议您使用字段掩码来指定您希望在响应中返回的字段。

警告： 在所有 v4 端点中，字段名称均采用小驼峰式命名法（例如 addressComponents），这与 v3 端点（采用蛇形命名法，例如 address_components）不同。与 v3 一样，RPC 响应在 v4 中继续使用蛇形命名法。

请求参数变更

v3 参数	v4 参数	备注
language	languageCode	已重命名。
region	regionCode	已重命名。
result_type	types	已重命名；使用重复的查询参数。
location_type	granularity	已重命名；使用重复的查询参数。
extra_computations	已移除

响应字段变更

v3 字段	v4 字段	备注
status、error_message	已移除	v4 使用 HTTP 状态代码和错误正文。
results.address_components.long_name/results.address_components.short_name	results.addressComponents.longText/results.addressComponents.shortText	已重命名。
results.geometry.location_type	results.granularity	已重命名。
results.geometry.location	results.location	字段名称：lat/lng -> latitude/longitude。
results.geometry.viewport	results.viewport	字段名称：northeast/southwest -> high/low。
全新设计	results.addressComponents.languageCode	特定地址组成部分的语言。
全新设计	results.bounds	使用 high/low 的显式边界。
全新设计	results.place	地点的资源名称。
全新设计	results.postalAddress	结构化 PostalAddress 对象。

从 v3 地点地理编码迁移

如果您使用 place_id 通过 Geocoding v3 获取特定地点 ID 的地址，则必须迁移到接受 GET 请求的 v4 Place Geocoding 端点。

v4 API 更改了多个参数的名称、结构和支持。我们强烈建议您使用字段掩码来指定您希望在响应中返回的字段。

警告： 在所有 v4 端点中，字段名称均采用小驼峰式命名法（例如 addressComponents），这与 v3 端点（采用蛇形命名法，例如 address_components）不同。与 v3 一样，RPC 响应在 v4 中继续使用蛇形命名法。

请求参数变更

v3 参数	v4 参数	备注
place_id	请求 proto 中的 place 字段	地点 ID 现在以路径参数 places/{place} 的形式提供，例如：https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw。这会映射到底层请求中的地点字段。
language	languageCode	已重命名。
region	regionCode	已重命名。

响应字段变更

v3 字段	v4 字段	备注
status、error_message	已移除	v4 使用 HTTP 状态代码和错误正文。
results	（根）	v4 返回单个结果对象，而不是 results 数组。
results.address_components.long_name/results.address_components.short_name	addressComponents.longText/addressComponents.shortText	已重命名。
results.geometry.location_type	granularity	已重命名。
results.geometry.location	location	字段名称：lat/lng -> latitude/longitude。
results.geometry.viewport	viewport	字段名称：northeast/southwest -> high/low。
results.postcode_localities	postalCodeLocalities	已重命名。现在，针对一个或多个地区返回（需要 v3 >1）。
全新设计	addressComponents.languageCode	特定地址组成部分的语言。
全新设计	bounds	使用 high/low 的显式边界。
全新设计	place	地点的资源名称。
全新设计	postalAddress	结构化 PostalAddress 对象。

从地理编码超本地数据迁移到目的地

Geocoding API v3 中的以下功能将由 Geocoding API v4 的 SearchDestinations 端点取代：

• 进入次数
• 导航点
• 构建轮廓
• 场地

如果您之前使用 Geocoding API v3 来实现上述功能，请参阅本文档，了解如何改用 SearchDestinations 端点来实现这些功能。本文档介绍了如何在 SearchDestinations API 响应中找到这些功能，以及 Geocoding API v3 和 Geocoding API v4 的 SearchDestinations 端点在 API 响应中表示这些功能的方式有何不同。

进入次数

如需获取与 destination 关联的入口，请使用字段 destination.entrances。

请注意，entrance 的格式与 Geocoding API v3 中的入口格式略有不同。destination.entrances 中的每个入口都包含以下字段：

• displayName - 这是一个新的可选字段，其中将包含入口的直观易懂的名称，例如“B 门”。
• location - 这是 LatLng 类型的地理位置，与 Geocoding API v3 中使用的格式不同。
• tags - 这与 Geocoding API v3 中入口的 tags 字段相同。
• place - 类似于 Geocoding API v3 中入口的 buildingPlaceId 字段。不过，此字段中的地点 ID 可以是任何类型的地点，不一定只是建筑物。

导航点

如需获取与 destination 关联的导航点，请使用字段 destination.navigationPoints。

请注意，navigationPoint 的格式与 Geocoding API v3 中的导航点格式略有不同。destination.navigationPoints 中的每个导航点都包含以下字段：

• displayName - 这是一个新的可选字段，其中将包含导航点的直观易懂的名称，例如“第五大道”。
• location - 这是 LatLng 类型的地理位置，与 Geocoding API v3 中使用的格式不同。
• travelModes - 这类似于 Geocoding API v3 中导航点的 restrictedTravelModes 字段。可能的枚举值相同，唯一的区别是，此字段现在表示导航点的可接受出行模式，而不是受限出行模式。
• usage - 这是一个新字段，包含导航点支持的用例。请注意，大多数导航点都会有 UNKNOWN 用法，但这并不一定意味着导航点的用法受到任何限制。

构建轮廓

如需获取与 destination 关联的建筑物轮廓，您应使用 destination 中表示建筑物的 placeView 对象的 displayPolygon 字段。对于每个 placeView，您可以使用 placeView.structureType 字段检查它是否为建筑物。如果结构类型为 BUILDING，您可以从 placeView.displayPolygon 字段获取轮廓。placeView 还将包含 Geocoding API v3 中没有的建筑物的其他字段。

注意： 只是想查找特定位置的建筑物多边形？您可以在请求中使用 placeFilter 参数来缩小结果范围。如需仅返回建筑结果，请在 placeFilter 中将 structureType 设置为 "BUILDING"。如果您优先考虑获取多边形（即使对于没有精确地址的位置也是如此），请在 placeFilter 中将 addressability 设置为 "ANY"，以返回最精确的多边形。

示例

{
  "locationQuery": {
    "location": {
      "latitude": 37.4224,
      "longitude": -122.0841
    },
    "placeFilter": {
      "structureType": "BUILDING",
      "addressability": "ANY"
    }
  }
}
  

destination 可以在以下字段中包含表示建筑物的 placeView 对象：

• destination.primary - 这是目标的主要位置。
• destination.containingPlaces - 这是重复字段，可包含“包含”主要地点的较大地点。例如，如果主要地点是 subpremise，containingPlaces 通常会保存表示相应建筑物的 placeView。
• destination.subDestinations - 这是重复字段，可包含主要地点的子目的地。例如，建筑物的各个公寓单元。此字段通常不会包含表示建筑物的 placeView。

请注意，placeView.displayPolygon 的格式与 Geocoding API v3 中的建筑轮廓格式（即 GeoJSON 格式，使用 RFC 7946 格式）相匹配。

场地

与构建轮廓类似，如需获取与 destination 关联的地面，您应使用 destination 中表示地面的 placeView 对象的 displayPolygon 字段。对于每个 placeView，您可以使用 placeView.structureType 字段检查它是否为理由。如果结构类型为 GROUNDS，您可以从 placeView.displayPolygon 字段获取轮廓。placeView 还将包含 Geocoding API v3 中没有的其他字段。

destination 可以具有 placeView 对象，该对象表示以下字段中的理由：

• destination.primary
• destination.containingPlaces
• destination.subDestinations

请注意，placeView.displayPolygon 的格式与 Geocoding API v3 中的场地轮廓格式（即 GeoJSON 格式，使用 RFC 7946 格式）相匹配。

使用字段遮盖来请求这些功能

SearchDestinations 端点需要一个字段掩码，如选择要返回的字段中所述。您可以将字段掩码设置为 * 以返回所有字段，也可以将其设置为您要接收的特定字段。例如，以下 API 请求设置了字段掩码，以接收获取目的地入口、导航点、建筑物轮廓和地面所需的所有字段：

curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
  -H "X-Goog-Api-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary,destinations.containingPlaces,destinations.subDestinations" \
  https://geocode.googleapis.com/v4alpha/geocode/destinations