下頁包含 Route Optimization API optimizeTours 方法下列元件的參數表 (依字母順序排列)：
這些參數表格只會列出頂層物件和主要參數，並簡要說明，方便您探索。如需完整清單，包括完整說明和所有巢狀參數，請參閱 API 參考說明文件。
要求主體
要求主體包含下列元素，右側的圖表和下表均有說明：
OptimizeToursRequest：頂層要求物件，內含模型和解決參數。ShipmentModel：包含貨運、車輛和全域限制的核心資料結構。Shipment：包含取貨和送貨的任務。VisitRequest：取貨或送貨地點和限制。
Vehicle：可執行出貨作業的車輛。
| 父項 | 參數 | 物業類型 | 說明 |
|---|---|---|---|
OptimizeToursRequest |
allowLargeDeadlineDespiteInterruptionRisk |
布林值 (true/false) |
如果為 true，即使逾時時間設為較大的值 (超過 30 分鐘)，可能會導致伺服器中斷，系統仍會處理要求。 |
considerRoadTraffic |
布林值 (true/false) |
如果 true，則使用流量資料進行路徑設定。如果為 false，則只會使用道路網路速度。 |
|
geodesicMetersPerSecond |
數字 | 如果 useGeodesicDistances 為 true，系統會使用這個速度計算行程時間。 |
|
injectedFirstSolutionRoutes[] |
物件陣列 (ShipmentRoute) |
要從先前的解決方案開始最佳化的路線。 | |
injectedSolutionConstraint |
object (InjectedSolutionConstraint) |
限制解決方案與現有路線相似，並指定必須保留哪些屬性，以及可放寬哪些屬性。 | |
interpretInjectedSolutionsUsingLabels |
布林值 (true/false) |
如果 true，則會依據 label 比對注入路徑中的貨運/車輛，而非陣列索引。 |
|
label |
字串 | 用於識別要求的任意標籤，會傳回至回應。 | |
maxValidationErrors |
整數 | 指定要傳回的驗證錯誤數量上限。如未指定，系統會套用預設限制。 | |
model |
object (ShipmentModel) |
必填。要最佳化的一組車輛和貨運。 | |
populatePolylines |
布林值 (true/false) |
如果值為 true，則會傳回路線的編碼折線。 |
|
populateTransitionPolylines |
布林值 (true/false) |
如果 true，則會傳回各次造訪之間轉換的編碼折線。 |
|
refreshDetailsRoutes[] |
物件陣列 (ShipmentRoute) |
要重新整理的路徑清單。這會重新計算現有路線的折線、時間長度和距離，但不會修改拜訪順序。 | |
searchMode |
enum (SearchMode) |
RETURN_FAST (快速結果) 或 CONSUME_ALL_AVAILABLE_TIME (逾時前提供最佳品質)。 |
|
solvingMode |
enum (SolvingMode) |
DEFAULT_SOLVE (預設) 或 VALIDATE_ONLY，即可驗證模型，不必解決問題。 |
|
timeout |
時間長度 | 求解器應執行的最長時數 (例如 「30s」、「300s」)。 | |
useGeodesicDistances |
布林值 (true/false) |
如果使用 true，系統會根據測地線 (直線) 距離和 geodesicMetersPerSecond 速度計算移動距離和時間。 |
|
ShipmentModel( OptimizeToursRequest 的一部分) |
durationDistanceMatrices[] |
物件陣列 (DurationDistanceMatrix) |
指定用於位置之間路徑規劃的自訂時間和距離矩陣。 |
durationDistanceMatrixDstTags[] |
字串陣列 | 定義自訂時間和距離矩陣目的地的標記 (資料欄)。 | |
durationDistanceMatrixSrcTags[] |
字串陣列 | 定義自訂時間和距離矩陣來源 (列) 的標記。 | |
globalDurationCostPerHour |
數字 | 路線全球時區的每小時成本，從最早的車輛出發時間到最晚的車輛結束時間。 | |
globalEndTime |
時間戳記 | 模型中任何事件的最新結束時間。 | |
globalStartTime |
時間戳記 | 模型中任何活動的最早開始時間。 | |
maxActiveVehicles |
整數 | 解決方案中可啟用的車輛數量上限。 | |
precedenceRules[] |
物件陣列 (PrecedenceRule) |
定義特定出貨項目之間訂購限制的規則。 | |
shipments[] |
物件陣列 (Shipment) |
要處理的貨運清單。 | |
shipmentTypeIncompatibilities[] |
物件陣列 (ShipmentTypeIncompatibility) |
規則：防止同一輛車輛運送特定類型的貨物。 | |
shipmentTypeRequirements[] |
物件陣列 (ShipmentTypeRequirement) |
規定特定類型的貨物必須由同一輛車運送。 | |
transitionAttributes[] |
物件陣列 (TransitionAttributes) |
指定具有特定標記的拜訪行程之間轉換的額外費用、延遲和距離限制。 | |
vehicles[] |
物件陣列 (Vehicle) |
可執行出貨作業的車輛清單。 | |
Shipment( ShipmentModel 的一部分) |
allowedVehicleIndices[] |
整數陣列 | 允許執行這項出貨作業的車輛索引。 |
costsPerVehicle[] |
map (key: integer, value: number) | 如果特定車輛負責運送這批貨物，則會產生額外費用。 | |
costsPerVehicleIndices[] |
整數陣列 | 適用 costsPerVehicle 值的車輛索引。 |
|
deliveries[] |
物件陣列 (VisitRequest) |
其他運送方式。 | |
ignore |
布林值 (true/false) |
如果為 true，系統會忽略這批貨件，不會用於最佳化。 |
|
label |
字串 | 使用者定義的標籤，用於識別出貨內容，並在回應中傳回。 | |
loadDemands |
map (key: string, value: Load) |
運送這批貨物所需的容量 (例如重量、體積)。 | |
penaltyCost |
數字 | 如果貨件不在服務範圍內，如未設定，則必須出貨。 | |
pickups[] |
物件陣列 (VisitRequest) |
其他取貨方式。 | |
pickupToDeliveryAbsoluteDetourLimit |
時間長度 | 取貨和送達之間允許的最大絕對繞道時間，與直達路徑相比。 | |
pickupToDeliveryRelativeDetourLimit |
數字 | 貨件允許的最大相對繞道值 (例如，值為 2.0 表示總時間最多可為直接旅行時間的 2 倍)。 | |
pickupToDeliveryTimeLimit |
時間長度 | 從取貨開始到送達開始之間允許的最長時限。 | |
shipmentType |
字串 | 用於不相容和需求規則的類型分類。 | |
VisitRequest( pickups 和 deliveries 的元件，位於 Shipment 中) |
arrivalLocation |
object (LatLng) |
抵達地點的地理位置，以經緯度座標表示。 |
arrivalWaypoint |
object (Waypoint) |
車輛抵達的地點，可執行拜訪作業。以座標或地點 ID 定義。 | |
cost |
數字 | 如果解決人員選取這項特定拜訪要求，您需要支付的費用。 | |
departureLocation |
object (LatLng) |
出發地點的地理位置，以經緯度座標表示。 | |
departureWaypoint |
object (Waypoint) |
車輛在完成拜訪後出發的地點。如果省略，系統會假設與 arrivalWaypoint 相同。 |
|
duration |
時間長度 | 造訪時間 (服務時間)，例如裝卸貨物所需的時間。 | |
label |
字串 | 這個特定造訪要求的自訂標籤，會傳回至回應。 | |
loadDemands |
map (key: string, value: Load) |
要求指定本次造訪的負重變化 (例如-1 即可將包裹交給快遞員)。 | |
tags[] |
字串陣列 | 附加至這項造訪要求的標記。這些時間戳記可用於計算這次造訪與其他造訪之間的間隔時間 (使用 transitionAttributes)。 |
|
timeWindows[] |
物件陣列 (TimeWindow) |
允許抵達此訪視的時間範圍。 | |
visitTypes[] |
字串陣列 | 說明造訪類型的字串 (例如 「delivery」(運送)、「installation」(安裝)。用於套用車輛模型中的 extraVisitDurationForVisitType。 |
|
Vehicle( ShipmentModel 的一部分) |
breakRule |
object (BreakRule) |
定義休息規則 (例如強制午休)。 |
costPerHour |
數字 | 總路線時長的每小時費用。 | |
costPerKilometer |
數字 | 每公里行駛費用。 | |
costPerTraveledHour |
數字 | 車輛行駛時的每小時費用。 | |
endLocation |
object (LatLng) |
地理位置的終點，以經緯度座標表示。 | |
endTags[] |
字串陣列 | 定義車輛最終狀態的標記，用於轉換屬性。 | |
endTimeWindows[] |
物件陣列 (TimeWindow) |
車輛可結束路線的允許時間範圍。 | |
endWaypoint |
object (Waypoint) |
使用 Waypoint (座標或地點 ID) 的地理位置終點。 | |
extraVisitDurationForVisitType |
map (key: string, value: Duration) | 根據造訪記錄的 visitType，為造訪記錄新增額外時間。 |
|
fixedCost |
數字 | 無論路線距離或時間長度，只要使用車輛就會套用的固定費用。 | |
ignore |
布林值 (true/false) |
如果為 true，系統會忽略車輛，不會用於最佳化。 |
|
label |
字串 | 車輛的使用者定義標籤，會顯示在回應中。 | |
loadLimits |
map (key: string, value: LoadLimit) |
車輛容量 (例如最大重量、最大體積)。 | |
routeDistanceLimit |
object (DistanceLimit) |
車輛路線總距離的硬性或軟性限制。 | |
routeDurationLimit |
object (DurationLimit) |
車輛路線總時長的硬性或軟性限制。 | |
routeModifiers |
object (RouteModifiers) |
一或多項限制，例如避開收費站、高速公路或渡輪。 | |
startLocation |
object (LatLng) |
地理位置的起點，以經緯度座標表示。 | |
startTags[] |
字串陣列 | 定義車輛的起始狀態，用於轉換屬性。 | |
startTimeWindows[] |
物件陣列 (TimeWindow) |
車輛可開始路線的允許時間範圍。 | |
startWaypoint |
object (Waypoint) |
使用航點 (座標或地點 ID) 的地理起點位置。 | |
travelDurationLimit |
object (DurationLimit) |
車輛總行程時間的硬性或軟性限制 (不含等待/服務時間)。 | |
travelDurationMultiple |
數字 | 套用至行程時間的乘數 (例如 1.5 會使行程時間增加 50%)。 | |
travelMode |
enum (TravelMode) |
交通方式 (例如DRIVING、WALKING)。這會影響交通時間和距離。 |
|
unloadingPolicy |
enum (UnloadingPolicy) |
定義卸貨順序 (例如 LIFO 或 LAST_IN_FIRST_OUT)。 |
|
usedIfRouteIsEmpty |
布林值 (true/false) |
如果 true，即使沒有出貨，車輛仍視為已使用。這類車輛會產生固定費用，並在起點和終點之間移動。 |
回應主體
回應內容包含下列元素，如右側圖表所示，並列於下表：
OptimizeToursResponse：頂層回應物件，內含最佳化路線和指標。Metrics：解決方案的整體成本和執行統計資料。ShipmentRoute：指派給單一車輛的拜訪順序和行車路徑。Visit：路線上的停靠點，用於取貨或送貨。Transition：兩個路線停靠站之間的行車路徑和時間。AggregatedMetrics：時間、距離和其他指標的總和。這個元素可同時存在於Metrics和ShipmentRoute中。
| 父項 | 參數 | 物業類型 | 說明 |
|---|---|---|---|
OptimizeToursResponse |
metrics |
object (Metrics) |
解決方案的匯總指標，包括總費用、總距離、總時長和車輛使用次數。 |
requestLabel |
字串 | 從要求的 label 欄位複製的標籤。用於將回應與原始要求建立關聯。 |
|
routes[] |
物件陣列 (ShipmentRoute) |
為每輛車計算出的路線清單。無論車輛是否使用，都會包含車輛的項目。 | |
skippedShipments[] |
物件陣列 (SkippedShipment) |
遭略過 (未提供服務) 的出貨清單，以及略過原因。 | |
validationErrors[] |
物件陣列 (OptimizeToursValidationError) |
輸入模型中發現的驗證錯誤清單。如果 solvingMode 設為 VALIDATE_ONLY，或是在解決問題時發生錯誤，系統就會填入這個欄位。 |
|
Metrics( OptimizeToursResponse 的一部分) |
aggregatedRouteMetrics |
object (AggregatedMetrics) |
所有路線的匯總統計資料，例如總行車距離、總時長和等待時間。 |
costs |
map (key: string, value: number) | 依類型細分的費用 (例如：「model.vehicles.cost_per_kilometer」、「model.shipments.penalty_cost」)。 | |
earliestVehicleStartTime |
時間戳記 | 所有使用車輛的最早開始時間。 | |
latestVehicleEndTime |
時間戳記 | 所有使用車輛的最新結束時間。 | |
skippedMandatoryShipmentCount |
整數 | 略過的強制出貨次數。 | |
totalCost |
數字 | 解決方案的總費用，包括所有路線費用和跳過出貨的罰款。 | |
usedVehicleCount |
整數 | 解決方案中使用的車輛數量。 | |
AggregatedMetrics( Metrics 和 ShipmentRoute 的一部分) |
breakDuration |
時間長度 | 所有路線的休息時間總長。 |
costs |
map (key: string, value: number) | 依類型細分的費用 (例如：「model.vehicles.cost_per_kilometer」、「model.shipments.penalty_cost」)。 | |
delayDuration |
時間長度 | 所有路線的總延誤時間。 | |
earliestVehicleStartTime |
時間戳記 | 所有使用車輛的最早開始時間。 | |
latestVehicleEndTime |
時間戳記 | 所有使用車輛的最新結束時間。 | |
maxLoads |
map (key: string, value: VehicleLoad) |
解決方案中任何車輛在任何時間點的最大負載，以負載類型做為鍵。 | |
performedShipmentCount |
整數 | 所有車輛的總出貨次數。 | |
skippedMandatoryShipmentCount |
整數 | 略過的強制出貨次數。 | |
totalCost |
數字 | 解決方案的總費用，包括所有路線費用和跳過出貨的罰款。 | |
totalDuration |
時間長度 | 所有路線的總時長 (交通 + 等候 + 延誤 + 休息 + 拜訪)。 | |
travelDistanceMeters |
數字 | 所有路線的總行駛距離 (以公尺為單位)。 | |
travelDuration |
時間長度 | 所有路線的總旅行時間。 | |
usedVehicleCount |
整數 | 解決方案中使用的車輛數量。 | |
visitDuration |
時間長度 | 所有路線的造訪總時間 (裝卸貨)。 | |
waitDuration |
時間長度 | 所有路徑的總等待時間。 | |
ShipmentRoute( OptimizeToursResponse 的一部分) |
breaks[] |
物件陣列 (Break) |
車輛在路線中休息的清單。 |
hasTrafficInfeasibilities |
布林值 (true/false) |
指出路線是否有任何交通相關的不可行性。 | |
metrics |
object (AggregatedMetrics) |
這條路線的專屬指標，例如總行駛距離和時間。 | |
routeCosts |
map (key: string, value: number) | 這條路線的費用明細。鍵是費用類型 (例如 「cost_per_hour」)，值則是金額。 | |
routePolyline |
object (EncodedPolyline) |
代表路線完整地理路徑的編碼折線。 | |
routeTotalCost |
數字 | 路線總費用，即 routeCosts 地圖中所有費用的總和。 |
|
transitions[] |
物件陣列 (Transition) |
連接造訪的轉換 (旅遊行程) 排序清單。 | |
vehicleEndTime |
時間戳記 | 車輛完成路線的時間。 | |
vehicleIndex |
整數 | 執行這條路線的來源 ShipmentModel 中車輛的索引。 |
|
vehicleLabel |
字串 | 車輛的使用者定義標籤，從要求模型複製而來。 | |
vehicleStartTime |
時間戳記 | 車輛開始行駛路線的時間。 | |
visits[] |
物件陣列 (Visit) |
車輛在這條路線上依序造訪的地點 (取貨和送貨)。 | |
Visit( ShipmentRoute 的一部分) |
detour |
時間長度 | 與前次和下次拜訪之間的直接路徑相比，這次拜訪所產生的額外繞道時間。 |
isPickup |
布林值 (true/false) |
如果為 true，代表這趟行程是取貨行程。如果為 false，則為外送。 |
|
loadDemands |
map (key: string, value: Load) |
這次拜訪滿足的負載需求 (例如，外送為 -1)。這是對應VisitRequest負載需求的副本。 |
|
shipmentIndex |
整數 | 這個拜訪服務的來源模型中 Shipment 欄位的索引。 |
|
shipmentLabel |
字串 | 從 ShipmentModel 複製的貨運標籤。 |
|
startTime |
時間戳記 | 預定開始時間。 | |
visitLabel |
字串 | 從模型中的 VisitRequest 複製的預約要求標籤。 |
|
visitRequestIndex |
整數 | 與本次拜訪相應的貨件取貨或送達清單中的 VisitRequest 索引。 |
|
Transition( ShipmentRoute 的一部分) |
breakDuration |
時間長度 | 這段期間的休息時間長度。 |
delayDuration |
時間長度 | 這段期間的延遲時間 (例如提早抵達並等待時間範圍)。 | |
routePolyline |
object (EncodedPolyline) |
代表這項特定轉換路徑的編碼折線。 | |
routeToken |
字串 | 不透明權杖，可傳遞至 Google Navigation SDK，在導航期間重建路線。 | |
startTime |
時間戳記 | 這項轉換的開始時間。 | |
totalDuration |
時間長度 | 轉換的總時間長度，包括旅行、等待、休息和延誤。 | |
trafficInfoUnavailable |
布林值 (true/false) |
如果 true，表示這項轉換沒有可用的流量資料。 |
|
travelDistanceMeters |
數字 | 轉換期間的移動距離，單位為公尺。 | |
travelDuration |
時間長度 | 這段期間的旅行時間。 | |
vehicleLoads |
map (key: string, value: VehicleLoad) |
車輛在轉換期間運送的負載，以負載類型做為鍵 (例如 「weight」)。 | |
waitDuration |
時間長度 | 下一次拜訪前等待的時間長度。 |