- HTTP 要求
- 要求主體
- 回應主體
- 授權範圍
- SearchDestinationsRequest.AddressQuery
- SearchDestinationsRequest.LocationQuery
- SearchDestinationsRequest.LocationQuery.PlaceFilter
- PlaceView.StructureType
- SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability
- NavigationPoint.TravelMode
- 目的地
- PlaceView
- PlaceView.AddressComponent
- 地標
- Landmark.Tag
- 入口
- Entrance.Tag
- StreetViewThumbnail
- ImageAnnotation
- ImageAnnotation.Coordinate
- NavigationPoint
- NavigationPoint.Usage
- Destination.ParkingOptions
- Destination.ParkingOptions.Availability
- Destination.ArrivalSummary
這個方法會執行目的地查詢,並傳回目的地清單。
HTTP 要求
POST https://geocode.googleapis.com/v4alpha/geocode/destinations
這個網址使用 gRPC 轉碼語法。
要求主體
要求主體會包含結構如下的資料:
| JSON 表示法 |
|---|
{ "travelModes": [ enum ( |
| 欄位 | |
|---|---|
travelModes[] |
(選用步驟) 用於篩選導覽點的交通方式。這會影響回應中傳回的 |
languageCode |
(選用步驟) 傳回結果時應使用的語言。 |
regionCode |
(選用步驟) 區域代碼。區碼,指定為 ccTLD (「頂層網域」) 的兩位字元值。這個參數會根據適用法律影響結果。這項參數也會影響 (但不會完全限制) 服務傳回的結果。 |
聯集欄位 目的地是根據指定的主要查詢建立。 注意:系統僅支援可做為導航目的地的地點和地址。舉例來說,代表房屋或公寓大樓的地點可用做主要查詢,但代表地區或行政區的地點則不可。 |
|
place |
地點的資源名稱,格式為 |
addressQuery |
街道地址。 |
locationQuery |
精確位置。 |
回應主體
DestinationService.SearchDestinations 的回應訊息。
如果成功,回應主體會含有以下結構的資料:
| JSON 表示法 |
|---|
{
"destinations": [
{
object ( |
| 欄位 | |
|---|---|
destinations[] |
目的地清單。 如果能從主要查詢中明確識別出主要目的地,服務就會傳回一項結果。否則,服務可能會傳回多個結果以消除歧義,或傳回零個結果。 |
授權範圍
需要下列其中一種 OAuth 範圍:
https://www.googleapis.com/auth/cloud-platformhttps://www.googleapis.com/auth/maps-platform.geocodehttps://www.googleapis.com/auth/maps-platform.destinations
SearchDestinationsRequest.AddressQuery
要搜尋的街道地址。遵循相關國家/地區郵政服務所使用的格式指定地址。
| JSON 表示法 |
|---|
{ // Union field |
| 欄位 | |
|---|---|
聯集欄位 kind。地址查詢。kind 只能是下列其中一項: |
|
address |
郵寄地址格式的街道地址。 |
addressQuery |
格式為單行的街道地址。 |
SearchDestinationsRequest.LocationQuery
用於找出附近主要目的地的位置查詢。
注意:如果位置查詢位於含有子場所的建築物內,傳回的主要地點可能是子場所。在這些情況下,containingPlaces 欄位會包含建築物。
| JSON 表示法 |
|---|
{ "placeFilter": { object ( |
| 欄位 | |
|---|---|
placeFilter |
(選用步驟) 要套用至候選目的地的篩選器。 |
聯集欄位 kind。位置查詢。kind 只能是下列其中一項: |
|
location |
精確的 LatLng 位置。 |
SearchDestinationsRequest.LocationQuery.PlaceFilter
要套用至候選目的地的篩選器。
| JSON 表示法 |
|---|
{ "structureType": enum ( |
| 欄位 | |
|---|---|
structureType |
(選用步驟) 如果指定,所有目的地都保證會有一個採用這種結構類型的主要地點。這可能會導致系統篩除部分目的地,或是粗略/精細地篩選傳回的目的地。 舉例來說,如果指定 這個欄位的另一個用途是更輕鬆地擷取建築物顯示多邊形。舉例來說,如果指定 |
addressability |
(選用步驟) 如果指定,則只會傳回符合相應可尋址性條件的目的地。 |
PlaceView.StructureType
這個地點代表的建築物類型。
| 列舉 | |
|---|---|
STRUCTURE_TYPE_UNSPECIFIED |
未使用。 |
POINT |
點位置。 |
SECTION |
建築物的子區域。 |
BUILDING |
建築物。 |
GROUNDS |
通常包含多棟建築物的大型區域,例如大學校園、公寓大樓或購物中心。 |
SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability
定義可定址性篩選條件的選項。日後可能會新增其他值。
| 列舉 | |
|---|---|
ADDRESSABILITY_UNSPECIFIED |
如未指定,服務會選擇合理的預設值。 |
ANY |
可定址性並非篩選條件。無論目的地是否可定址,系統都會傳回。 |
PRIMARY |
傳回的所有目的地都會有主要地點,並附上街道層級的地址或名稱。 |
WEAK |
系統傳回的所有目的地都會有主要地點或子目的地,以及街道層級的地址或名稱。 |
目的地
目的地。包括主要地點、相關地點、入口和導航點。
| JSON 表示法 |
|---|
{ "primary": { object ( |
| 欄位 | |
|---|---|
primary |
要求中 |
containingPlaces[] |
包含主要地點的較不精確地點。例如,包含這棟建築物的公寓大樓。 |
subDestinations[] |
主要地點的更精確子目的地。例如建築物內的單元。 注意:與 Places API 傳回的 SubDestination 相比,這份子目的地清單更詳盡,且每個子目的地都包含更多資訊。 |
landmarks[] |
可用來告知目的地位置或協助抵達的地標。 |
entrances[] |
這個目的地的入口。 |
navigationPoints[] |
這個目的地的導航點。 |
parkingOptions |
這個目的地的停車選項。 |
arrivalSummary |
AI 生成的摘要,說明抵達目的地時的體驗。 |
PlaceView
代表 Places API 中地點的檢視畫面。此外,這項服務也會提供目的地專屬的其他資訊,例如結構類型和顯示多邊形。
在某些情況下,具有相同地點 ID 的 PlaceView,可能與 Places API 針對 types 和 displayName 欄位傳回的內容不同。
| JSON 表示法 |
|---|
{ "place": string, "displayName": { object ( |
| 欄位 | |
|---|---|
place |
這個地點的資源名稱,格式為 |
placeId |
地點的專屬 ID。 |
displayName |
使用者可理解的地點說明。例如「B 閘口」、「麥當勞」 |
primaryType |
這個地點的主要地點類型。如要查看可能的值清單,請前往 https://developers.google.com/maps/documentation/places/web-service/place-types。 注意:這個欄位不一定會填入內容。在這種情況下,請準備使用 |
types[] |
這個地點的所有相關地點類型。如需可能的值清單,請參閱 https://developers.google.com/maps/documentation/places/web-service/place-types。 |
formattedAddress |
單行地址。 |
postalAddress |
結構化地址。 |
structureType |
與這個地點對應的建築物類型。 |
location |
這個地點的位置。如果地點有多邊形顯示,這可能代表在地圖上放置標記的好位置。 |
displayPolygon |
地點的多邊形輪廓,採用 GeoJSON 格式,並符合 RFC 7946 格式:https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.6。 注意:RFC 7946 格式支援 MultiPolygon,因此一個 |
addressComponents[] |
每個地區層級的重複元件。 |
PlaceView.AddressComponent
組成格式化地址的結構化元件 (如有)。
| JSON 表示法 |
|---|
{ "longText": string, "shortText": string, "types": [ string ], "languageCode": string } |
| 欄位 | |
|---|---|
longText |
地址元件的完整文字說明或名稱。舉例來說,澳洲這個國家/地區的地址元件,全名可能是「Australia」。 |
shortText |
地址元件的縮寫文字名稱 (如有)。舉例來說,澳洲地址元件的簡稱可能為「AU」。 |
types[] |
指出地址元件類型的陣列。 詳情請參閱 https://developers.google.com/maps/documentation/geocoding/requests-geocoding#Types。 |
languageCode |
用於設定這個元件格式的語言 (以 CLDR 標記法表示)。 |
地標
地標可用於說明目的地位置,或協助抵達目的地。
| JSON 表示法 |
|---|
{ "relationalDescription": { object ( |
| 欄位 | |
|---|---|
relationalDescription |
目的地與地標關係的人類可讀說明。例如「帝國大廈附近」或「白宮對面」。 |
tags[] |
標記:說明地標在目的地情境中的用途。 |
straightLineDistanceMeters |
僅供輸出。從這個地標到目的地的直線距離 (以公尺為單位)。 |
travelDistanceMeters |
僅供輸出。從這個地標到目的地的步行距離 (以公尺為單位)。 |
聯集欄位 landmark。地標。landmark 只能是下列其中一項: |
|
place |
代表這個地標的地點。 |
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 ( |
| 欄位 | |
|---|---|
location |
入口位置。 |
tags[] |
描述入口的標記清單。 |
place |
這個入口實際所在的建築物,格式為 |
streetViewThumbnail |
顯示入口的街景服務縮圖。您可以向 Street View Static API 要求圖片。請參閱 https://developers.google.com/maps/documentation/streetview/request-streetview。 |
streetViewAnnotation |
在上方傳回的 |
Entrance.Tag
描述入口的特徵。
| 列舉 | |
|---|---|
TAG_UNSPECIFIED |
未使用。 |
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 |
特定全景 ID。 |
widthPx |
輸出縮圖的寬度 (以像素為單位)。注意:如果要求註解和縮圖,請務必在街景服務 API 要求中使用這些高度和寬度值,確保註解座標與圖片正確對齊。 |
heightPx |
輸出縮圖的高度 (以像素為單位)。注意:在要求註解和縮圖時,必須在街景服務 API 要求中使用這些高度和寬度值,確保註解座標與圖片正確對齊。 |
headingDegree |
相機的水平方向 (以度為單位)。範圍 [0, 360)。0 代表北方,90 代表東方。 |
pitchDegree |
相機的垂直方向 (以度為單位)。範圍 [-90, 90]。0 代表水平,+90 代表垂直向上,-90 代表垂直向下。 |
fovDegree |
水平視野 (以度為單位)。範圍 (0, 180]。控制縮放等級。視野越小,表示放大倍率越高。 |
ImageAnnotation
圖片縮圖上的註解,例如標示入口的凸多邊形。
| JSON 表示法 |
|---|
{
"coordinates": [
{
object ( |
| 欄位 | |
|---|---|
coordinates[] |
在圖片上形成多邊形的座標清單。座標會依逆時針順序排列。 |
ImageAnnotation.Coordinate
圖片上某個點的像素座標。原點 (0,0) 是圖片左上角像素的左上角,x 軸指向右側,y 軸指向下方。
| JSON 表示法 |
|---|
{ "xPx": number, "yPx": number } |
| 欄位 | |
|---|---|
xPx |
X 座標。 |
yPx |
Y 座標。 |
Destination.ParkingOptions
目的地停車選項的相關資訊。
| JSON 表示法 |
|---|
{
"availability": enum ( |
| 欄位 | |
|---|---|
availability |
這個目的地的停車位供應情形。 |
onsiteParking |
目的地附設停車場。 |
freeParkingLot |
提供免費停車場。 |
paidParkingLot |
提供付費停車場。 |
freeStreetParking |
提供免費路邊車位。 |
paidStreetParking |
提供付費路邊車位。 |
valetParking |
提供代客泊車服務。 |
freeGarageParking |
提供免費室內停車場。 |
paidGarageParking |
提供付費室內停車場。 |
Destination.ParkingOptions.Availability
造訪這個地點時,尋找停車位的難易度匯總指標。
日後可能會新增其他值。
| 列舉 | |
|---|---|
AVAILABILITY_UNSPECIFIED |
無法提供停車資訊。 |
PLENTY |
提供充足的停車位。 |
SOMEWHAT_DIFFICULT |
停車位有點難找。 |
DIFFICULT |
停車位非常難找。 |
Destination.ArrivalSummary
AI 生成的摘要,說明抵達目的地時的體驗。
| JSON 表示法 |
|---|
{ "text": { object ( |
| 欄位 | |
|---|---|
text |
目的地抵達體驗的摘要。 |
flagContentUrl |
使用者可透過這個連結回報摘要問題。 |
disclosureText |
僅供輸出。包含抵達摘要的揭露文字。 |