从 v3 功能迁移到 SearchDestinations 端点
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
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 - 这是一个新的可选字段，其中将包含入口的人类可读名称，例如“Gate 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 中没有的建筑物的其他字段。
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.primarydestination.containingPlacesdestination.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
如未另行说明，那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可，并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情，请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC)：2025-08-31。
[null,null,["最后更新时间 (UTC)：2025-08-31。"],[],[],null,["# Migrate from v3 features to the SearchDestinations endpoint\n\n\u003cbr /\u003e\n\n| This product or feature is Experimental (pre-GA). Pre-GA products and features might have limited support, and changes to pre-GA products and features might not be compatible with other pre-GA versions. Pre-GA Offerings are covered by the [Google\n| Maps Platform Service Specific Terms](https://cloud.google.com/maps-platform/terms/maps-service-terms). For more information, see the [launch stage descriptions](/maps/launch-stages).\n\n\u003cbr /\u003e\n\n**European Economic Area (EEA) developers** If your billing address is in the European Economic Area, effective on 8 July 2025, the [Google Maps Platform EEA Terms of Service](https://cloud.google.com/terms/maps-platform/eea) will apply to your use of the Services. Functionality varies by region. [Learn more](/maps/comms/eea/faq).\n\nThe following features in the Geocoding API v3 are being replaced by the\n[SearchDestinations](/maps/documentation/geocoding/search-for-destinations)\nendpoint of the Geocoding API v4:\n\n- Entrances\n- Navigation points\n- Building outlines\n- Grounds\n\nIf you were using the Geocoding API v3 for the above features, use this document\nto help you use the SearchDestinations endpoint instead to get these features.\nThis document explains where in the SearchDestinations API response to find\nthese features, and differences in how these features are represented in the API\nresponses between the Geocoding API v3 and the SearchDestinations endpoint of\nthe Geocoding API v4.\n\nEntrances\n---------\n\nTo get the entrances associated with a\n[`destination`](/maps/documentation/geocoding/reference/rest/v4alpha/geocode.destinations/searchDestinations#destination),\nuse the field `destination.entrances`.\n\nNote that the format of an\n[`entrance`](/maps/documentation/geocoding/reference/rest/v4alpha/geocode.destinations/searchDestinations#entrance)\nis slightly different from the\n[entrance format in the Geocoding API v3](/maps/documentation/geocoding/building-attributes).\nEach entrance in `destination.entrances` has the following fields:\n\n- `displayName` - this is a new optional field that will have a human readable name for the entrance, for example \"Gate B\".\n- `location` - this is a location of type [`LatLng`](/maps/documentation/geocoding/reference/rest/Shared.Types/LatLng), which is different from the format used in the Geocoding API v3.\n- `tags` - this is the same as the `tags` field of the entrances from the Geocoding API v3.\n- `place` - analogous to the `buildingPlaceId` field of the entrances from the Geocoding API v3. However, the Place ID in this field could be for a Place of any type, not necessarily just a building.\n\nNavigation points\n-----------------\n\nTo get the navigation points associated with a `destination`, use the field\n`destination.navigationPoints`.\n\nNote that the format of a\n[`navigationPoint`](/maps/documentation/geocoding/reference/rest/v4alpha/geocode.destinations/searchDestinations#navigationpoint)\nis slightly different from the\n[navigation point format in the Geocoding API v3](/maps/documentation/geocoding/navigation-points).\nEach navigation point in `destination.navigationPoints` has the following\nfields:\n\n- `displayName` - this is a new optional field that will have a human readable name for the navigation point, for example \"5th Ave\".\n- `location` - this is a location of type [`LatLng`](/maps/documentation/geocoding/reference/rest/Shared.Types/LatLng), which is different from the format used in the Geocoding API v3.\n- `travelModes` - this is similar to the `restrictedTravelModes` field of the navigation points from the Geocoding API v3. The possible enum values are the same, the only difference is that this field now represents the acceptable travel modes for the navigation point, rather than the restricted travel modes.\n- `usage` - this is a new field which contains the use cases supported by the navigation point. Note that most navigation points will have an `UNKNOWN` usage, but that does not necessarily mean the navigation point's usage is restricted in any way.\n\nBuilding outlines\n-----------------\n\nTo get the building outlines associated with a `destination`, you should\nuse the `displayPolygon` field of the\n[`placeView`](/maps/documentation/geocoding/reference/rest/v4alpha/geocode.destinations/searchDestinations#placeview)\nobjects in the `destination` that represent buildings. For each `placeView`,\nyou can check if it is a building with the\n[`placeView.structureType`](/maps/documentation/geocoding/reference/rest/v4alpha/geocode.destinations/searchDestinations#placeview.structuretype)\nfield. If the structure type is `BUILDING`, you can get the outline from the\n`placeView.displayPolygon` field. The `placeView` will also have additional\nfields for the building that were not in the Geocoding API v3.\n\nA `destination` can have a `placeView` object that represents a building in the\nfollowing fields:\n\n- `destination.primary` - this is the primary place for the destination.\n- `destination.containingPlaces` - this is a repeated field that can hold larger places that \"contain\" the primary place. For example, if the primary place is a `subpremise`, `containingPlaces` will usually hold the `placeView` representing the building.\n- `destination.subDestinations` - this is a repeated field that can hold sub-destinations of the primary place. For example, individual apartment units of a building. This field won't typically have a `placeView` representing a building.\n\nNote that the format of `placeView.displayPolygon` matches the\n[building outline format in the Geocoding API v3](/maps/documentation/geocoding/building-attributes),\nwhich is the GeoJSON format, using the\n[RFC 7946 format](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.6).\n\nGrounds\n-------\n\nSimilar to building outlines, to get the grounds associated with a\n`destination`, you should use the `displayPolygon` field of the `placeView`\nobjects in the `destination` that represent grounds. For each `placeView`, you\ncan check if it is a grounds with the `placeView.structureType` field. If the\nstructure type is `GROUNDS`, you can get the outline from the\n`placeView.displayPolygon` field. The `placeView` will also have additional\nfields for the grounds that were not in the Geocoding API v3.\n\nA `destination` can have a `placeView` object that represents a grounds in the\nfollowing fields:\n\n- `destination.primary`\n- `destination.containingPlaces`\n- `destination.subDestinations`\n\nNote that the format of `placeView.displayPolygon` matches the\n[grounds outline format in the Geocoding API v3](/maps/documentation/geocoding/grounds),\nwhich is the GeoJSON format, using the\n[RFC 7946 format](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.6).\n\nUse a field mask to request these features\n------------------------------------------\n\nThe [SearchDestinations](/maps/documentation/geocoding/search-for-destinations)\nendpoint requires a field mask, as explained in\n[Choose fields to return](/maps/documentation/geocoding/choose-fields). The\nfield mask can be set to `*` in order to return all fields, or you can set it to\nthe specific fields you want to receive. For example, the following API request\nsets the field mask to receive all fields required to get the entrances,\nnavigation points, building outlines, and grounds of a destination: \n\n```curl\ncurl -X POST -d '{\"place\": \"places/ChIJG3kh4hq6j4AR_XuFQnV0_t8\"}' \\\n -H \"X-Goog-Api-Key: API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary,destinations.containingPlaces,destinations.subDestinations\" \\\n https://geocode.googleapis.com/v4alpha/geocode/destinations\n```"]]
