Method: geocode.destinations.searchDestinations

此方法会执行目的地查找并返回目的地列表。

HTTP 请求

POST https://geocode.googleapis.com/v4beta/geocode/destinations

网址采用 gRPC 转码语法。

请求正文

请求正文中包含结构如下的数据：

JSON 表示法 
{
  "travelModes": [
    enum (NavigationPoint.TravelMode)
  ],
  "languageCode": string,
  "regionCode": string,

  // Union field primary_query can be only one of the following:
  "place": string,
  "addressQuery": {
    object (SearchDestinationsRequest.AddressQuery)
  },
  "locationQuery": {
    object (SearchDestinationsRequest.LocationQuery)
  }
  // End of list of possible types for union field primary_query.
}
字段
travelModes[]

enum (NavigationPoint.TravelMode)

可选。用于过滤导航点的出行方式。这会影响响应中返回的 navigationPoints 字段。如果为空，则系统会返回所有出行方式的导航点。
languageCode

string

可选。返回结果时应使用的语言。
regionCode

string

可选。地区代码。地区代码，以 ccTLD（“顶级域名”）双字符值的形式指定。该参数会根据适用法律影响结果。此参数还会影响但不会完全限制服务中的结果。

联合字段 primary_query。查询主要目的地。可以是地点、完全指定的地址或 LatLng 位置。某些信息极少的地点和地址无法转换为目的地。

目标位置是围绕指定的主查询构建的。

注意：仅支持可作为导航目的地的地点和地址。例如，代表独栋房屋或公寓大楼的地点可用作主查询，但代表市行政区或行政区的地点不能用作主查询。primary_query 只能是下列其中一项：
place

string

地点的资源名称，格式为 places/{placeId}。
addressQuery

object (SearchDestinationsRequest.AddressQuery)

街道地址。
locationQuery

object (SearchDestinationsRequest.LocationQuery)

精确位置。

响应正文

DestinationService.SearchDestinations 的响应消息。

如果成功，响应正文将包含结构如下的数据：

JSON 表示法 
{
  "destinations": [
    {
      object (Destination)
    }
  ]
}
字段
destinations[]

object (Destination)

目的地列表。

如果可以从主查询中明确识别出主要目的地，则该服务会返回一个结果。否则，该服务可能会返回多个结果以消除歧义，也可能返回零个结果。

授权范围

需要以下 OAuth 范围之一：

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/maps-platform.geocode
  • https://www.googleapis.com/auth/maps-platform.destinations

SearchDestinationsRequest.AddressQuery

您要搜索的街道地址。按照相关国家全国邮政服务使用的格式指定地址

JSON 表示法 
{

  // Union field kind can be only one of the following:
  "address": {
    object (PostalAddress)
  },
  "addressQuery": string
  // End of list of possible types for union field kind.
}
字段
联合字段 kind。地址查询。kind 只能是下列其中一项：
address

object (PostalAddress)

邮政地址格式的街道地址。
addressQuery

string

格式为单行的街道地址。

SearchDestinationsRequest.LocationQuery

用于识别附近主要目的地的位置查询。

注意：如果位置查询位于包含子场所的建筑物内，则返回的主要地点可能是子场所。在这些情况下，containingPlaces 字段将包含建筑物。

JSON 表示法 
{
  "placeFilter": {
    object (SearchDestinationsRequest.LocationQuery.PlaceFilter)
  },

  // Union field kind can be only one of the following:
  "location": {
    object (LatLng)
  }
  // End of list of possible types for union field kind.
}
字段
placeFilter

object (SearchDestinationsRequest.LocationQuery.PlaceFilter)

可选。要应用于候选目的地的过滤条件。
联合字段 kind。地点查询。kind 只能是下列其中一项：
location

object (LatLng)

精确的 LatLng 位置。

SearchDestinationsRequest.LocationQuery.PlaceFilter

要应用于候选目的地的过滤条件。

JSON 表示法 
{
  "structureType": enum (PlaceView.StructureType),
  "addressability": enum (SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability)
}
字段
structureType

enum (PlaceView.StructureType)

可选。如果指定了此参数，则保证所有目的地都具有此结构类型的主要地点。这可能会导致过滤掉某些目的地，或使返回的目的地变得更粗略/更精细。

例如，如果指定了 GROUNDS，则返回的所有目的地都将具有结构类型为 GROUNDS 的主要地点。这可能会导致过滤掉部分不属于场地一部分的目的地，或者将返回的目的地粗化到场地级别。

此字段的另一个用途是更轻松地提取建筑物显示多边形。例如，如果指定了 BUILDING，则主要地点的显示多边形将对应于指定位置处的建筑物。
addressability

enum (SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability)

可选。如果指定，则仅返回符合相应可寻址性条件的目的地。

PlaceView.StructureType

此地点所代表的结构类型。

枚举
STRUCTURE_TYPE_UNSPECIFIED 未使用。
POINT 点位置。
SECTION 建筑物的子部分。
BUILDING 一栋建筑。
GROUNDS 通常包含多栋建筑的大型区域，例如大学校园、公寓楼群或购物中心。

SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability

定义了可寻址性过滤的选项。未来可能会添加新值。

枚举
ADDRESSABILITY_UNSPECIFIED 如果未指定，服务将选择合理的默认值。
ANY 可寻址性不是过滤条件。无论目的地是否可寻址，系统都会返回相应目的地。
PRIMARY 返回的所有目的地都将包含具有街道级地址或名称的主要地点。
WEAK 返回的所有目的地都将包含主要地点或具有街道级地址或名称的子目的地。

目的地

目的地。这包括主要地点、相关地点、入口和导航点。

JSON 表示法 
{
  "primary": {
    object (PlaceView)
  },
  "containingPlaces": [
    {
      object (PlaceView)
    }
  ],
  "subDestinations": [
    {
      object (PlaceView)
    }
  ],
  "landmarks": [
    {
      object (Landmark)
    }
  ],
  "entrances": [
    {
      object (Entrance)
    }
  ],
  "navigationPoints": [
    {
      object (NavigationPoint)
    }
  ]
}
字段
primary

object (PlaceView)

请求中由 primary_query 标识的主要地点。
containingPlaces[]

object (PlaceView)

包含主要地点的不太精确的地点。例如，包含此建筑物的公寓楼群。
subDestinations[]

object (PlaceView)

主要地点的更精确的子目的地。例如，建筑物中包含的单元。

注意：与 Places API 返回的 SubDestination 相比，此子目的地列表更详尽，并且每个子目的地都包含更多信息。
landmarks[]

object (Landmark)

可用于传达目的地位置或帮助到达目的地的地标。
entrances[]

object (Entrance)

此目的地的入口。
navigationPoints[]

object (NavigationPoint)

相应目的地的导航点。

PlaceView

表示 Places API 中 Place 的视图。它还提供特定于目的地的其他信息，例如结构类型和显示多边形。

在某些情况下，具有相同地点 ID 的 PlaceView 可能会与 Places API 为 types 和 displayName 字段返回的内容不同。

JSON 表示法 
{
  "place": string,
  "placeId": string,
  "displayName": {
    object (LocalizedText)
  },
  "primaryType": string,
  "types": [
    string
  ],
  "formattedAddress": string,
  "postalAddress": {
    object (PostalAddress)
  },
  "structureType": enum (PlaceView.StructureType),
  "location": {
    object (LatLng)
  },
  "displayPolygon": {
    object
  },
  "addressComponents": [
    {
      object (PlaceView.AddressComponent)
    }
  ]
}
字段
place

string

此地点的资源名称，格式为 places/{placeId}。可用于查找地点。
placeId

string

地点的唯一标识符。
displayName

object (LocalizedText)

人类可读的位置说明。例如“B 门”“麦当劳”
primaryType

string

相应地点的主要地点类型。如需查看可能的值列表，请参阅 https://developers.google.com/maps/documentation/places/web-service/place-types。

注意：此字段并不总是填充。请做好准备，在这种情况下使用 types 字段。
types[]

string

此地点的所有关联地点类型。如需查看可能的值列表，请参阅 https://developers.google.com/maps/documentation/places/web-service/place-types。
formattedAddress

string

单行地址。
postalAddress

object (PostalAddress)

结构化地址。
structureType

enum (PlaceView.StructureType)

与此地点对应的结构类型。
location

object (LatLng)

相应地点的位置。对于具有显示多边形的地点，这可以表示在地图上放置标记的合适位置。
displayPolygon

object (Struct format)

采用 GeoJSON 格式的地点多边形轮廓，使用 RFC 7946 格式：https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.6。

注意：RFC 7946 格式支持 MultiPolygon，因此一个 displayPolygon 对象可以表示多个多边形。
addressComponents[]

object (PlaceView.AddressComponent)

每个行政区划层级的重复组件。

PlaceView.AddressComponent

构成格式化地址的结构化组件（如果此信息可用）。

JSON 表示法 
{
  "longText": string,
  "shortText": string,
  "types": [
    string
  ],
  "languageCode": string
}
字段
longText

string

地址组成部分的完整文本说明或名称。例如，澳大利亚的地址组成部分可能包含长名称“Australia”。
shortText

string

地址组成部分的缩写文本名称（如果有）。例如，澳大利亚的地址组成部分可能具有“AU”的简称。
types[]

string

一个数组，表示地址组成部分的类型。

如需了解详情，请参阅 https://developers.google.com/maps/documentation/geocoding/requests-geocoding#Types。
languageCode

string

用于设置此组件格式的语言（采用 CLDR 表示法）。

地标

地标用于传达目的地所在位置或帮助用户到达目的地。

JSON 表示法 
{
  "relationalDescription": {
    object (LocalizedText)
  },
  "tags": [
    enum (Landmark.Tag)
  ],
  "straightLineDistanceMeters": number,
  "travelDistanceMeters": number,

  // Union field landmark can be only one of the following:
  "place": {
    object (PlaceView)
  }
  // End of list of possible types for union field landmark.
}
字段
relationalDescription

object (LocalizedText)

目的地与地标之间的关系的人类可读说明。例如：“帝国大厦附近”或“白宫对面”。
tags[]

enum (Landmark.Tag)

用于描述地标在目的地背景下的用途的标记。
straightLineDistanceMeters

number

仅限输出。从相应地标到目的地的直线距离（以米为单位）。
travelDistanceMeters

number

仅限输出。从相应地标到目的地的步行距离（以米为单位）。
联合字段 landmark。地标。landmark 只能是下列其中一项：
place

object (PlaceView)

表示相应地标的位置。

Landmark.Tag

描述地标在目的地背景下如何使用的所有可能标记的列表。

如果某个地址同时具有 ADDRESS 和 ARRIVAL 标记，则表示该地标既在当地知名，又靠近目的地。

枚举
TAG_UNSPECIFIED 未使用。
ADDRESS 可用于识别目的地大致位置的当地知名地点。通常在目的地几百米范围内。这些地标类似于 Geocoding API 的地址描述符功能返回的地标：https://developers.google.com/maps/documentation/geocoding/address-descriptors/requests-address-descriptors。
ARRIVAL 可用于帮助到达目的地的地点。当您接近目的地时，此功能有助于导航。例如，此地标可能是目的地对面的某个地点。与带有 ADDRESS 标记的地标相比，带有此标记的地标通常更靠近目的地。

入口

入口是指单个纬度/经度坐标对，用于定义某个地点的入口和出口点的位置。

JSON 表示法 
{
  "location": {
    object (LatLng)
  },
  "tags": [
    enum (Entrance.Tag)
  ],
  "place": string
}
字段
location

object (LatLng)

入口的位置。
tags[]

enum (Entrance.Tag)

描述入口的一系列标签。
place

string

入口所位于的结构，采用 places/{placeId} 格式。

Entrance.Tag

描述入口的特征。

枚举
TAG_UNSPECIFIED 未使用。
PREFERRED

入口可能提供对返回的目的地中主要地点的实际访问权限。一个地点可以有多个首选入口。如果入口没有此标签，则表示该入口在物理上与主要地点位于同一建筑物，但不一定能通往该地点。

例如，如果主要地点是露天购物中心内的一家餐厅，则“PREFERRED”入口可能是通往餐厅本身的入口，而返回的其他入口则是建筑物的其他入口，例如通往露天购物中心内其他餐厅的入口。

如果主要地点本身是一栋建筑，则 PREFERRED 入口将是通往建筑“主要”部分的入口。例如，在购物中心，PREFERRED 入口是通往主门厅区域的入口，但如果某个入口只能通往建筑物一侧的商店，则它不是PREFERRED入口。

注意：PREFERRED 入口可能无法通往主要地点，而非 PREFERRED 入口可能可以通往主要地点。