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 中的 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}。可用於查詢地點。
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 物件可以代表多個多邊形。

地標

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

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)

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