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

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 表示法 
{

  // Union field kind can be only one of the following:
  "location": {
    object (LatLng)
  }
  // End of list of possible types for union field kind.
}
欄位
聯集欄位 kind。位置查詢。kind 只能是下列其中一項：
location

object (LatLng)

精確的 LatLng 位置。

目的地

目的地。包括主要地點、相關地點、入口和導航點。

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,
  "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}。
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 物件可以代表多個多邊形。

PlaceView.StructureType

這個地點代表的結構類型。

列舉
STRUCTURE_TYPE_UNSPECIFIED 未使用。
POINT 點位置。
SECTION 建築物的子區域。
BUILDING 建築物。
GROUNDS 通常包含多棟建築物的大型區域，例如大學校園、公寓大樓或購物中心。

地標

地標可用來指出目的地位置，或協助抵達目的地。

JSON 表示法 
{
  "tags": [
    enum (Landmark.Tag)
  ],

  // Union field landmark can be only one of the following:
  "place": {
    object (PlaceView)
  }
  // End of list of possible types for union field landmark.
}
欄位
tags[]

enum (Landmark.Tag)

標記，說明地標在目的地情境中的用途。
聯集欄位 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 入口則可能可以。