Method: geocode.destinations.searchDestinations

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

HTTP 请求

POST https://geocode.googleapis.com/v4alpha/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)
    }
  ],
  "parkingOptions": {
    object (Destination.ParkingOptions)
  },
  "arrivalSummary": {
    object (Destination.ArrivalSummary)
  }
}
字段
primary

object (PlaceView)

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

object (PlaceView)

包含主要位置的精度较低的位置。例如，包含此建筑物的公寓楼群。
subDestinations[]

object (PlaceView)

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

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

object (Landmark)

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

object (Entrance)

相应目的地的入口。
navigationPoints[]

object (NavigationPoint)

相应目的地的导航点。
parkingOptions

object (Destination.ParkingOptions)

相应目的地的停车选项。
arrivalSummary

object (Destination.ArrivalSummary)

AI 生成的到达目的地后的体验摘要。

PlaceView

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

在某些情况下，具有相同地点 ID 的 PlaceView 可能与 Places API 针对 types 和 displayName 字段返回的结果不同。

JSON 表示法 
{
  "place": string,
  "displayName": {
    object (LocalizedText)
  },
  "primaryType": string,
  "types": [
    string
  ],
  "formattedAddress": string,
  "postalAddress": {
    object (PostalAddress)
  },
  "structureType": enum (PlaceView.StructureType),
  "location": {
    object (LatLng)
  },
  "displayPolygon": {
    object
  }
}
字段
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 对象可以表示多个多边形。

地标

地标用于指示目的地所在的位置，或帮助您到达目的地。

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,
  "streetViewThumbnail": {
    object (StreetViewThumbnail)
  },
  "streetViewAnnotation": {
    object (ImageAnnotation)
  }
}
字段
location

object (LatLng)

入口的位置。
tags[]

enum (Entrance.Tag)

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

string

入口所在的实体的结构，采用 places/{placeId} 格式。
streetViewThumbnail

object (StreetViewThumbnail)

显示入口的街景缩略图。可以通过 Street View Static API 请求该图片。请参阅 https://developers.google.com/maps/documentation/streetview/request-streetview。
streetViewAnnotation

object (ImageAnnotation)

上面返回的 streetViewThumbnail 中入口的注释。

Entrance.Tag

描述入口的特征。

枚举
TAG_UNSPECIFIED 未使用。
PREFERRED

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

例如，如果主要地点是某个带状购物中心内的餐厅，“首选”入口很可能是直接通往餐厅的入口，而返回的其他入口则是该建筑物的其他入口，例如通往带状购物中心内其他餐厅的入口。

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

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

StreetViewThumbnail

用于表示 Google 街景缩略图的参数。这些参数可用于通过 Street View Static API 请求街景图像。请参阅 https://developers.google.com/maps/documentation/streetview/request-streetview。

JSON 表示法 
{
  "pano": string,
  "widthPx": integer,
  "heightPx": integer,
  "headingDegree": number,
  "pitchDegree": number,
  "fovDegree": number
}
字段
pano

string

特定全景图片的 ID。
widthPx

integer

输出缩略图的宽度（以像素为单位）。注意：如果要在请求缩略图的同时请求注释，则必须在 Street View API 请求中使用这些高度和宽度值，以确保注释坐标与图片正确对齐。
heightPx

integer

输出缩略图的高度（以像素为单位）。注意：如果要在请求缩略图的同时请求注释，则必须在 Street View API 请求中使用这些高度和宽度值，以确保注释坐标与图片正确对齐。
headingDegree

number

摄像头的水平方向（以度为单位）。范围 [0, 360)。0 表示北，90 表示东。
pitchDegree

number

摄像头的垂直方向（以度为单位）。范围 [-90, 90]。0 为地平线，+90 为垂直向上，-90 为垂直向下。
fovDegree

number

水平视野范围（以度为单位）。范围 (0, 180]。控制缩放级别。视场角越小，变焦程度越高。

ImageAnnotation

图片缩略图上的注释，例如勾勒出入口的多边形。

JSON 表示法 
{
  "coordinates": [
    {
      object (ImageAnnotation.Coordinate)
    }
  ]
}
字段
coordinates[]

object (ImageAnnotation.Coordinate)

构成图片上多边形的一系列坐标。坐标按逆时针顺序排列。

ImageAnnotation.Coordinate

图片上某个点的像素坐标。原点 (0,0) 是图片左上角像素的左上角，x 轴指向右侧，y 轴指向下方。

JSON 表示法 
{
  "xPx": number,
  "yPx": number
}
字段
xPx

number

X 坐标。
yPx

number

Y 坐标。

Destination.ParkingOptions

有关目的地的停车选项的信息。

JSON 表示法 
{
  "availability": enum (Destination.ParkingOptions.Availability),
  "onsiteParking": boolean,
  "freeParkingLot": boolean,
  "paidParkingLot": boolean,
  "freeStreetParking": boolean,
  "paidStreetParking": boolean,
  "valetParking": boolean,
  "freeGarageParking": boolean,
  "paidGarageParking": boolean
}
字段
availability

enum (Destination.ParkingOptions.Availability)

相应目的地的停车位提供情况。
onsiteParking

boolean

目的地设有酒店内停车场。
freeParkingLot

boolean

提供免费停车场。
paidParkingLot

boolean

提供收费停车场。
freeStreetParking

boolean

提供免费路边停车位。
paidStreetParking

boolean

提供收费路边停车位。
valetParking

boolean

提供代客泊车服务。
freeGarageParking

boolean

提供免费停车库。
paidGarageParking

boolean

提供收费停车库。

Destination.ParkingOptions.Availability

一种汇总衡量指标，用于衡量前往相应地点时寻找停车位的难易程度。

未来可能会添加新值。

枚举
AVAILABILITY_UNSPECIFIED 无法查看停车位情况。
PLENTY 酒店提供充足的停车位。
SOMEWHAT_DIFFICULT 找停车位有点难。
DIFFICULT 很难找到停车位。

Destination.ArrivalSummary

AI 生成的到达目的地后的体验摘要。

JSON 表示法 
{
  "text": {
    object (LocalizedText)
  },
  "flagContentUrl": string,
  "disclosureText": {
    object (LocalizedText)
  }
}
字段
text

object (LocalizedText)

目的地到达体验的摘要。
flagContentUrl

string

一个链接，用户可以通过该链接标记摘要存在的问题。
disclosureText

object (LocalizedText)

仅限输出。包含到达摘要的披露声明文本。