- HTTP 要求
- 路徑參數
- 要求主體
- 回應主體
- VehicleAttributeList
- VehicleMatchOrder
- CurrentTripsPresent
- VehicleMatch
- 旅行點
- VehicleMatchType
傳回與要求選項相符的車輛清單。
HTTP 要求
POST https://fleetengine.googleapis.com/v1/{parent=providers/*}/vehicles:search
這個網址使用 gRPC 轉碼語法。
路徑參數
參數 | |
---|---|
parent |
必要欄位。格式須為 |
要求主體
要求主體的資料會採用以下結構:
JSON 表示法 |
---|
{ "header": { object ( |
欄位 | |
---|---|
header |
標準 Fleet Engine 要求標頭。 |
pickupPoint |
必要欄位。要搜尋的上車地點。 |
dropoffPoint |
客戶預計的下車地點。如果 |
pickupRadiusMeters |
必要欄位。定義取貨點周圍的車輛搜尋半徑。系統只會傳回搜尋半徑範圍內的車輛。值必須介於 400 至 10000 公尺 (含) 之間。 |
count |
必要欄位。指定傳回的車輛數量上限。這個值必須介於 1 至 50 (含) 之間。 |
minimumCapacity |
必要欄位。指定行程的乘客人數。這個值必須大於或等於 1。容量值不會計入驅動程式。 |
tripTypes[] |
必要欄位。代表建議行程的類型。必須只包含一種類型。不允許使用 |
maximumStaleness |
僅搜尋在指定時間內傳送位置更新資訊至 Fleet Engine 的車輛。即使一般車輛仍在傳輸位置資訊,也不算過時。如未設定這個欄位,伺服器會使用 5 分鐘做為預設值。 持續時間以秒為單位,最多 9 個小數位數,結尾為「 |
vehicleTypes[] |
必要欄位。將搜尋範圍限制在符合其中一個指定類型的車輛。至少須指定一種交通工具類型。不允許使用類別為 |
requiredAttributes[] |
呼叫端可以使用
將搜尋範圍限制在含有指定屬性的車輛。這個欄位是結合/AND 作業。最多只能有 50 個必要屬性。這與車輛允許的屬性數量上限相符。 |
requiredOneOfAttributes[] |
僅搜尋各 |
requiredOneOfAttributeSets[] |
與
僅搜尋具有 |
orderBy |
必要欄位。為結果指定所需的排序條件。 |
includeBackToBack |
指出是否只有單一有效行程的車輛可執行這項搜尋。只有在未指定 預設值為 |
tripId |
表示與這個 |
currentTripsPresent |
表示有有效行程的車輛是否可執行這項搜尋。如果 |
filter |
選用設定。搜尋車輛時要套用的篩選查詢。如需篩選器語法範例,請參閱 http://aip.dev/160。 這個欄位是用來取代 這個篩選函式可做為 AND 子句,但具有其他限制條件,例如 請注意,只有車輛屬性 (例如 此外,所有屬性都會儲存為字串,因此唯一支援與屬性的比較是字串比較。如要與數字或布林值比較,您必須明確加上引號,才能視為字串 (例如 |
回應主體
vehicles.search
回應訊息。
如果成功,回應主體會含有以下結構的資料:
JSON 表示法 |
---|
{
"matches": [
{
object ( |
欄位 | |
---|---|
matches[] |
符合 |
VehicleAttributeList
車輛屬性的清單資料類型清單。
JSON 表示法 |
---|
{
"attributes": [
{
object ( |
欄位 | |
---|---|
attributes[] |
這個集合中的屬性清單。 |
VehicleMatchOrder
指定回應中的車輛比對順序。
列舉 | |
---|---|
UNKNOWN_VEHICLE_MATCH_ORDER |
預設,用於未指定或無法辨識的車輛比對順序。 |
PICKUP_POINT_ETA |
依車輛行駛時間遞增排序,直到抵達上車地點。 |
PICKUP_POINT_DISTANCE |
根據車輛行駛距離至上車地點的遞增順序。 |
DROPOFF_POINT_ETA |
依車輛行駛時間遞增排序,直到抵達下車地點。只有在要求中指定下車地點時,才能使用此順序。 |
PICKUP_POINT_STRAIGHT_DISTANCE |
按照與車輛最後回報的位置到上車地點之間的直線距離遞增排序。 |
COST |
依設定的比對費用遞增排序。比對費用是指以直線距離與預計到達時間之間的加權計算。權重是以預設值設定,每位客戶可以修改。如要為專案修改這些權重,請與 Google 支援團隊聯絡。 |
CurrentTripsPresent
指定車輛目前行程的限制類型。
列舉 | |
---|---|
CURRENT_TRIPS_PRESENT_UNSPECIFIED |
可預訂行程的車輛取決於 includeBackToBack 欄位。 |
NONE |
不含行程的車輛可能會顯示在搜尋結果中。使用這個值時,includeBackToBack 不得為 true 。 |
ANY |
搜尋結果將包含目前最多 5 趟行程和 10 個路線控點的車輛。使用這個值時,includeBackToBack 不得為 true 。 |
VehicleMatch
包含車輛與車輛 SearchVehiclesRequest
中有效行程點相符的車輛和相關預估資料。
JSON 表示法 |
---|
{ "vehicle": { object ( |
欄位 | |
---|---|
vehicle |
必要欄位。與要求相符的車輛。 |
vehiclePickupEta |
車輛的行車預計到達時間,前往要求中指定的取貨地點。如果值為空白,表示計算車輛預計到達時間失敗。如果 RFC3339 世界標準時間「Zulu」的時間戳記格式,解析度為奈秒,且最多 9 個小數位數。範例: |
vehiclePickupDistanceMeters |
車輛目前位置與要求中指定的上車地點之間的距離,包括現有行程的任何中繼上車或下車點。這個距離包括計算出的行車 (路線) 距離,以及導航終點與所要求取貨地點之間的直線距離。(導航終點與所要求的取貨地點之間的距離通常很小。)空白值表示計算距離時發生錯誤。 |
vehiclePickupStraightLineDistanceMeters |
必要欄位。車輛與要求中指定的取貨點之間的直線距離。 |
vehicleDropoffEta |
完整車輛的行車預計到達時間,前往要求中指定的下車地點。預計到達時間包括在要求中指定的 RFC3339 世界標準時間「Zulu」的時間戳記格式,解析度為奈秒,且最多 9 個小數位數。範例: |
vehiclePickupToDropoffDistanceMeters |
從上車點到要求中指定的下車地點的車輛行車距離 (以公尺為單位)。距離只介於兩點之間,不含車輛位置,或是車輛造訪上車地點或下車地點前必須造訪的任何其他點。只有在要求中指定 |
tripType |
必要欄位。要求的行程類型,用來計算抵達上車地點的預計到達時間。 |
vehicleTripsWaypoints[] |
用來計算預計到達時間的路線控點清單。這份清單包含車輛位置、車輛有效行程的取貨點,以及要求中提供的取貨點。如果清單空白,表示系統計算車輛預計到達時間時失敗。 |
vehicleMatchType |
相符的車輛類型。 |
requestedOrderedBy |
要求排序車輛相符項目的順序。 |
orderedBy |
這輛車的實際訂單。通常會比對「orderBy」欄位;不過,在某些情況下 (例如內部伺服器錯誤),則可使用其他方法 (例如 |
途經點
說明 SearchVehiclesResponse
中 VehicleMatch
路線沿途的中繼點。這個概念在所有其他端點中以 TripWaypoint
表示。
JSON 表示法 |
---|
{
"latLng": {
object ( |
欄位 | |
---|---|
latLng |
這個路線控點的位置。 |
eta |
車輛抵達這個路線控點的預計時間。 RFC3339 世界標準時間「Zulu」的時間戳記格式,解析度為奈秒,且最多 9 個小數位數。範例: |
VehicleMatchType
車輛比對類型。
列舉 | |
---|---|
UNKNOWN |
未知的車輛比對類型 |
EXCLUSIVE |
這輛車目前還沒有指定行程,可以繼續前往上車地點。 |
BACK_TO_BACK |
車輛目前已指派給行程,但完成行程後可繼續至上車地點。系統計算預計到達時間和距離時,會將現有行程納入考量。 |
CARPOOL |
車輛的容量足夠,可多人共乘。 |
CARPOOL_BACK_TO_BACK |
車輛會先完成目前進行中的行程,再前往上車地點。系統計算預計到達時間和距離時,會將現有行程納入考量。 |