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。查詢主要目的地。可以是地點、完整地址或經緯度位置。如果某些地點和地址的資訊過少,就無法設為目的地。

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

注意:系統僅支援可做為導航目的地的地點和地址。舉例來說,代表房屋或公寓大樓的地點可用做主要查詢,但代表地區或行政區的地點則不可。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 中地點的檢視畫面。此外,這項服務也會提供目的地專屬的其他資訊,例如結構類型和顯示多邊形。

在某些情況下,具有相同地點 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
  },
  "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

指出地址元件類型的陣列。

詳情請參閱 https://developers.google.com/maps/documentation/geocoding/requests-geocoding#Types。

languageCode

string

用於設定這個元件格式的語言 (以 CLDR 標記法表示)。

地標

地標可用於說明目的地位置,或協助抵達目的地。

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 入口可能無法通往主要地點,而非 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)

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