下頁包含 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 |
物件 (InjectedSolutionConstraint) |
限制解決方案與現有路線相似，指定必須保留哪些屬性，以及可以放寬哪些屬性。 | |
interpretInjectedSolutionsUsingLabels |
布林值 (true/false) |
如果為 true，則會根據 label (而非陣列索引) 比對插入路線中的運送/車輛。 |
|
label |
字串 | 用於識別要求的任意標籤，會在回應中傳回。 | |
maxValidationErrors |
整數 | 指定要傳回的驗證錯誤數量上限。如未指定，則會套用預設限制。 | |
model |
物件 (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[] |
對應 (鍵：整數，值：數字) | 如果由特定車輛運送這批貨物，會產生額外費用。 | |
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( Shipment中 pickups 和 deliveries 的元件) |
arrivalLocation |
物件 (LatLng) |
抵達地點的地理座標 (經緯度)。 |
arrivalWaypoint |
物件 (Waypoint) |
車輛抵達造訪地點的位置。由座標或地點 ID 定義。 | |
cost |
數字 | 如果求解器選取這項造訪要求，就會產生這筆費用。 | |
departureLocation |
物件 (LatLng) |
出發地點的地理經緯度座標。 | |
departureWaypoint |
物件 (Waypoint) |
車輛完成造訪後離開的地點。如未指定，則會假定與 arrivalWaypoint 相同。 |
|
duration |
時間長度 | 造訪時間長度 (服務時間)，例如裝載/卸載所需的時間。 | |
label |
字串 | 這項特定造訪要求的使用者定義標籤，會在回應中傳回。 | |
loadDemands |
map (key: string, value: Load) |
指定本次造訪時載重變化的需求 (例如 -1 表示卸下一個包裹)。 | |
tags[] |
字串陣列 | 附加至這項造訪要求的標記。系統會使用 transitionAttributes，根據這些資訊計算這項造訪與其他造訪之間的行程時間。 |
|
timeWindows[] |
物件陣列 (TimeWindow) |
抵達這項造訪地點的允許時間範圍。 | |
visitTypes[] |
字串陣列 | 描述造訪類型的字串 (例如「delivery」、「installation」)。用於套用車輛模型的 extraVisitDurationForVisitType。 |
|
Vehicle( ShipmentModel的一部分) |
breakRule |
物件 (BreakRule) |
定義休息時間規則 (例如強制午休)。 |
costPerHour |
數字 | 路線總時長每小時的費用。 | |
costPerKilometer |
數字 | 每公里行駛費用。 | |
costPerTraveledHour |
數字 | 車輛移動時每小時的費用。 | |
endLocation |
物件 (LatLng) |
地理位置終點，以經緯度座標表示。 | |
endTags[] |
字串陣列 | 定義車輛結束狀態的標記，用於轉換屬性。 | |
endTimeWindows[] |
物件陣列 (TimeWindow) |
車輛結束路線的時間範圍。 | |
endWaypoint |
物件 (Waypoint) |
使用路線控點 (座標或地點 ID) 的地理終點位置。 | |
extraVisitDurationForVisitType |
map (鍵：字串，值：Duration) | 根據visitType延長造訪時間。 |
|
fixedCost |
數字 | 使用車輛時產生的固定費用，與路線距離或時間長度無關。 | |
ignore |
布林值 (true/false) |
如果為 true，系統會忽略車輛，不納入最佳化。 |
|
label |
字串 | 車輛的使用者定義標籤，會在回應中傳回。 | |
loadLimits |
map (key: string, value: LoadLimit) |
車輛容量 (例如最大重量、最大體積)。 | |
routeDistanceLimit |
物件 (DistanceLimit) |
車輛路線總距離的硬性或軟性限制。 | |
routeDurationLimit |
物件 (DurationLimit) |
車輛路線總時間長度的硬性或軟性限制。 | |
routeModifiers |
物件 (RouteModifiers) |
一或多項限制，例如避開收費路段、高速公路或渡輪。 | |
startLocation |
物件 (LatLng) |
地理位置起點，以經緯度座標表示。 | |
startTags[] |
字串陣列 | 定義車輛起始狀態的標記，用於轉換屬性。 | |
startTimeWindows[] |
物件陣列 (TimeWindow) |
車輛可開始路線的時間範圍。 | |
startWaypoint |
物件 (Waypoint) |
使用路線控點 (座標或地點 ID) 的地理起點。 | |
travelDurationLimit |
物件 (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 |
物件 (Metrics) |
解決方案的匯總指標，包括總費用、總距離、總時間長度和車輛使用次數。 |
requestLabel |
字串 | 從要求的 label 欄位複製的標籤。用於將回應與原始要求建立關聯。 |
|
routes[] |
物件陣列 (ShipmentRoute) |
為每輛車計算出的路線清單。無論使用情況如何，每輛車都有一個項目。 | |
skippedShipments[] |
物件陣列 (SkippedShipment) |
略過 (未提供服務) 的運送清單，以及略過的原因。 | |
validationErrors[] |
物件陣列 (OptimizeToursValidationError) |
輸入模型中發現的驗證錯誤清單。如果 solvingMode 設為 VALIDATE_ONLY，或求解期間發生錯誤，系統就會填入這個欄位。 |
|
Metrics( OptimizeToursResponse的一部分) |
aggregatedRouteMetrics |
物件 (AggregatedMetrics) |
所有路線的匯總統計資料，例如總行經距離、總時間長度和等待時間。 |
costs |
對應 (鍵：字串，值：數字) | 依類型細分的費用 (例如「model.vehicles.cost_per_kilometer」、「model.shipments.penalty_cost」)。 | |
earliestVehicleStartTime |
時間戳記 | 所有使用車輛的最早開始時間。 | |
latestVehicleEndTime |
時間戳記 | 所有使用車輛的最新結束時間。 | |
skippedMandatoryShipmentCount |
整數 | 略過的必要運送作業數量。 | |
totalCost |
數字 | 解決方案的總成本，即所有路線成本和略過運送罰款的總和。 | |
usedVehicleCount |
整數 | 解決方案中使用的車輛數量。 | |
AggregatedMetrics( Metrics和ShipmentRoute的一部分) |
breakDuration |
時間長度 | 所有路線的休息總時長。 |
costs |
對應 (鍵：字串，值：數字) | 依類型細分的費用 (例如「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 |
物件 (AggregatedMetrics) |
這條路線的專屬指標，例如總距離和行駛時間。 | |
routeCosts |
對應 (鍵：字串，值：數字) | 這條路線的費用明細。鍵是費用類型 (例如「cost_per_hour」)，值則是金額。 | |
routePolyline |
物件 (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 |
物件 (EncodedPolyline) |
編碼折線，代表這項特定轉場的路徑。 | |
routeToken |
字串 | 不透明權杖，可傳遞至 Google Navigation SDK，在導航期間重建路線。 | |
startTime |
時間戳記 | 這項轉換作業的開始時間。 | |
totalDuration |
時間長度 | 轉乘總時間長度，包括交通、等待、休息和延遲時間。 | |
trafficInfoUnavailable |
布林值 (true/false) |
如果為 true，表示這項轉換沒有流量資料。 |
|
travelDistanceMeters |
數字 | 這段轉換期間移動的距離，以公尺為單位。 | |
travelDuration |
時間長度 | 這段轉換期間的移動時間。 | |
vehicleLoads |
map (key: string, value: VehicleLoad) |
車輛在轉換期間載運的貨物，以貨物類型 (例如「重量」) 為鍵。 | |
waitDuration |
時間長度 | 開始下一次造訪前等待的時間長度。 |