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)

(選用步驟) 用戶端要求的工作量。

查詢主要目的地。可以是地點、完整地址或經緯度位置。如果某些地點和地址的資訊過少，就無法設為目的地。

目的地是根據指定的主要查詢建立。

注意：僅支援可設為導航目的地的地點和地址。舉例來說，代表房屋或公寓大樓的地點可以做為主要查詢，但代表地區或行政區的地點則無法做為主要查詢。以下是互斥欄位清單。回應中最多會設定下列其中一個欄位：
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

地點的專屬 ID。
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 閘門」、「南側入口」、「第 5 大道入口」。
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

輸出縮圖的寬度 (以像素為單位)。注意：如果要求註解和縮圖，請務必在街景服務 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),
  "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)

僅供輸出。包含抵達摘要的揭露文字。