Method: geocode.destinations.searchDestinations

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

HTTP 请求

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

网址采用 gRPC 转码语法。

请求正文

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

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

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "place": string,
  "addressQuery": {
    object (SearchDestinationsRequest.AddressQuery)
  },
  "locationQuery": {
    object (SearchDestinationsRequest.LocationQuery)
  }
  // End of mutually exclusive fields.
}
字段
travelModes[]

enum (NavigationPoint.TravelMode)

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

string

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

string

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

enum (SearchDestinationsRequest.Effort)

可选。客户端请求的工作量级别。

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

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

注意：仅支持可作为导航目的地的地点和地址。例如，代表独栋房屋或公寓大楼的地点可用作主查询，但代表市行政区或行政区的地点不能用作主查询。以下是互斥字段列表。在响应中，最多只能设置其中一个字段：
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 表示法 
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "address": {
    object (PostalAddress)
  },
  "addressQuery": string
  // End of mutually exclusive fields.
}
字段
地址查询。以下是互斥字段列表。在响应中，最多只能设置其中一个字段：
address

object (PostalAddress)

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

string

格式为单行的街道地址。
互斥字段结束。

SearchDestinationsRequest.LocationQuery

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

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

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

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "location": {
    object (LatLng)
  }
  // End of mutually exclusive fields.
}
字段
placeFilter

object (SearchDestinationsRequest.LocationQuery.PlaceFilter)

可选。要应用于候选目的地的过滤条件。
地点查询。以下是互斥字段列表。在响应中，最多只能设置其中一个字段：
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 返回的所有目的地都将具有主要地点或具有街道级地址或名称的子目的地。

SearchDestinationsRequest.Effort

为解析目标位置而分配的工作量。

枚举
EFFORT_UNSPECIFIED 默认值。
LOW 注重提升响应速度。执行直接目的地查找，无需扩展层次结构遍历或复杂地点消歧。
MEDIUM 兼顾速度和准确性。大多数请求都会以标准的低延迟返回。对于含糊不清的查询、多建筑场所或难以确定的位置，该服务会进行额外处理，以解析目的地和层级上下文，延迟时间有限，最长可能需要几秒钟。建议用于用户可以容忍短暂暂停的交互式工作流。
HIGH 针对复杂、非正式或庞大的地点（例如大型校园或公寓大楼），最大限度地提高目的地解析的准确性和完整性。响应时间可能会显著延长。建议用于后台、批处理、调度或物流预路线规划工作流。

目的地

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

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

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

这些值取自 Places API 使用的地址类型和地址组成部分类型表：https://developers.google.com/maps/documentation/places/web-service/place-types#address-types
languageCode

string

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

地标

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

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

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "place": {
    object (PlaceView)
  }
  // End of mutually exclusive fields.
}
字段
relationalDescription

object (LocalizedText)

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

enum (Landmark.Tag)

描述地标在目的地背景下的使用方式的标签。
straightLineDistanceMeters

number

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

number

仅限输出。从该地标到目的地的步行距离（以米为单位）。
地标。以下是互斥字段列表。在响应中，最多只能设置其中一个字段：
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 表示法 
{
  "displayName": {
    object (LocalizedText)
  },
  "location": {
    object (LatLng)
  },
  "tags": [
    enum (Entrance.Tag)
  ],
  "place": string,
  "streetViewThumbnail": {
    object (StreetViewThumbnail)
  },
  "streetViewAnnotation": {
    object (ImageAnnotation)
  }
}
字段
displayName

object (LocalizedText)

人类可读名称，例如“B 门”“南入口”“第五大道入口”。
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 入口可能无法通往主要地点，而非 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]。控制缩放级别。FOV 越小，变焦倍数越大。

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),
  "parkingFacilities": [
    {
      object (Destination.ParkingOptions.ParkingFacility)
    }
  ],
  "onsiteParking": boolean,
  "freeParkingLot": boolean,
  "paidParkingLot": boolean,
  "freeStreetParking": boolean,
  "paidStreetParking": boolean,
  "valetParking": boolean,
  "freeGarageParking": boolean,
  "paidGarageParking": boolean
}
字段
availability

enum (Destination.ParkingOptions.Availability)

此目的地的停车位供应情况。
parkingFacilities[]

object (Destination.ParkingOptions.ParkingFacility)

此目的地的停车设施。
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.ParkingOptions.ParkingFacility

与目的地关联的单个、独立的停车选项（例如，特定的停车库或停车场）。此消息提供有关特定停车设施的详细信息，而父级 ParkingOptions 消息则提供所有可用停车位的汇总摘要。

JSON 表示法 
{
  "place": {
    object (PlaceView)
  },
  "onsite": boolean,
  "popular": boolean,
  "straightLineDistanceMeters": number
}
字段
place

object (PlaceView)

此特定停车设施的地点表示。
onsite

boolean

此停车设施是否位于主要目的地。如果未设置此字段，则现场状态未知。
popular

boolean

此停车设施是否是前往主要目的地的游客的热门选择。如果未设置此字段，则热门程度状态未知。
straightLineDistanceMeters

number

从主要目的地到此停车设施的直线距离（以米为单位）。

Destination.ArrivalSummary

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

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

object (LocalizedText)

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

string

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

object (LocalizedText)

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