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
  },
  "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,
  "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

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

integer

输出缩略图的高度（以像素为单位）。注意：如果要在请求缩略图的同时请求注释，则必须在街景 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)

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