Parameter list

The following page contains parameter tables in alphabetical order for the following components of the Route Optimization API optimizeTours method:

• Request body
• Response body

These parameter tables only list and briefly describes the top-level objects and main parameters for ease of discovery. For an exhaustive list with complete descriptions and all the nested parameters see the API reference documentation.

Request body

The request body includes the following elements, which are illustrated in the diagram to the right and listed in the table below:

• OptimizeToursRequest: The top-level request object containing the model and solving parameters.
  • ShipmentModel: The core data structure containing shipments, vehicles, and global constraints.
    • Shipment: A task with pickups and deliveries.
      • VisitRequest: The location and constraints for a pickup or delivery.
    • Vehicle: A vehicle available to perform shipments.

Parent	Parameter	Property type	Description
OptimizeToursRequest	allowLargeDeadlineDespiteInterruptionRisk	boolean (true/false)	If true, the request is processed even if the timeout is set to a large value (longer than 30 minutes) that risks potential server interruptions.
	considerRoadTraffic	boolean (true/false)	If true, uses traffic data for routing. If false, uses road network speeds only.
	geodesicMetersPerSecond	number	When useGeodesicDistances is true, this speed is used to calculate travel times.
	injectedFirstSolutionRoutes[]	array of objects (ShipmentRoute)	Routes from a previous solution to start the optimization from.
	injectedSolutionConstraint	object (InjectedSolutionConstraint)	Constrains the solution to be similar to existing routes, specifying which properties must be preserved and which may be relaxed.
	interpretInjectedSolutionsUsingLabels	boolean (true/false)	If true, matches shipments/vehicles in injected routes by their label instead of array index.
	label	string	Arbitrary label to identify the request, returned in the response.
	maxValidationErrors	integer	Specifies the maximum number of validation errors to return. If unspecified, a default limit applies.
	model	object (ShipmentModel)	Required. The set of vehicles and shipments to be optimized.
	populatePolylines	boolean (true/false)	If true, returns encoded polylines for routes.
	populateTransitionPolylines	boolean (true/false)	If true, returns encoded polylines for individual transitions between visits.
	refreshDetailsRoutes[]	array of objects (ShipmentRoute)	A list of routes to be refreshed. This recalculates polylines, durations, and distances for existing routes without modifying the visit sequence.
	searchMode	enum (SearchMode)	RETURN_FAST (quick results) or CONSUME_ALL_AVAILABLE_TIME (best quality within timeout).
	solvingMode	enum (SolvingMode)	DEFAULT_SOLVE (default) or VALIDATE_ONLY to validate the model without solving.
	timeout	Duration	The maximum duration the solver should run (e.g., "30s", "300s").
	useGeodesicDistances	boolean (true/false)	If true, travel distances and times are calculated using geodesic (straight-line) distances and the geodesicMetersPerSecond speed.
ShipmentModel (Part of OptimizeToursRequest)	durationDistanceMatrices[]	array of objects (DurationDistanceMatrix)	Specifies custom duration and distance matrixes used for routing between locations.
	durationDistanceMatrixDstTags[]	array of strings	Tags defining the destinations (columns) for the custom duration and distance matrixes.
	durationDistanceMatrixSrcTags[]	array of strings	Tags defining the sources (rows) for the custom duration and distance matrixes.
	globalDurationCostPerHour	number	Cost per hour of the global time span of the route, from the earliest vehicle start to the latest vehicle end.
	globalEndTime	Timestamp	Latest end time for any event in the model.
	globalStartTime	Timestamp	Earliest start time for any event in the model.
	maxActiveVehicles	integer	Maximum number of vehicles allowed to be active in the solution.
	precedenceRules[]	array of objects (PrecedenceRule)	Rules defining ordering constraints between specific shipments.
	shipments[]	array of objects (Shipment)	The list of shipments to be serviced.
	shipmentTypeIncompatibilities[]	array of objects (ShipmentTypeIncompatibility)	Rules preventing shipments of certain types from being serviced by the same vehicle.
	shipmentTypeRequirements[]	array of objects (ShipmentTypeRequirement)	Rules requiring shipments of certain types to be serviced by the same vehicle.
	transitionAttributes[]	array of objects (TransitionAttributes)	Specifies extra costs, delays, and distance limits for transitions between visits with specific tags.
	vehicles[]	array of objects (Vehicle)	The list of vehicles available to perform the shipments.
Shipment (Part of ShipmentModel)	allowedVehicleIndices[]	array of integers	Indices of vehicles allowed to perform this shipment.
	costsPerVehicle[]	map (key: integer, value: number)	Additional costs incurred if a specific vehicle services this shipment.
	costsPerVehicleIndices[]	array of integers	Indices of vehicles to which costsPerVehicle values apply.
	deliveries[]	array of objects (VisitRequest)	Alternatives for delivering the shipment.
	ignore	boolean (true/false)	If true, the shipment is ignored and not used in optimization.
	label	string	User-defined label for identifying the shipment, returned in the response.
	loadDemands	map (key: string, value: Load)	The capacity required (e.g., weight, volume) to carry this shipment.
	penaltyCost	number	Cost if the shipment is not serviced. If unset, the shipment is mandatory.
	pickups[]	array of objects (VisitRequest)	Alternatives for picking up the shipment.
	pickupToDeliveryAbsoluteDetourLimit	Duration	The maximum absolute detour time allowed between pickup and delivery compared to the direct path.
	pickupToDeliveryRelativeDetourLimit	number	The maximum relative detour allowed for the shipment (e.g., a value of 2.0 means the total time can be at most 2x the direct travel time).
	pickupToDeliveryTimeLimit	Duration	The maximum allowed duration from the start of the pickup to the start of the delivery.
	shipmentType	string	Type classification used for incompatibility and requirement rules.
VisitRequest (A component of pickups and deliveries in Shipment)	arrivalLocation	object (LatLng)	The geographic arrival location as latitude/longitude coordinates.
	arrivalWaypoint	object (Waypoint)	The location where the vehicle arrives to perform the visit. Defined by coordinates or a place ID.
	cost	number	The cost incurred if this specific visit request is selected by the solver.
	departureLocation	object (LatLng)	The geographic departure location as latitude/longitude coordinates.
	departureWaypoint	object (Waypoint)	The location where the vehicle departs after completing the visit. If omitted, it is assumed to be the same as the arrivalWaypoint.
	duration	Duration	The duration of the visit (service time), e.g., how long it takes to load/unload.
	label	string	User-defined label for this specific visit request, returned in the response.
	loadDemands	map (key: string, value: Load)	Demands specifying the load change at this visit (e.g., -1 to drop off a package).
	tags[]	array of strings	Tags attached to this visit request. These are used to calculate travel times between this visit and others using transitionAttributes.
	timeWindows[]	array of objects (TimeWindow)	The allowed time windows for the arrival at this visit.
	visitTypes[]	array of strings	Strings describing the type of visit (e.g., "delivery", "installation"). Used to apply extraVisitDurationForVisitType from the Vehicle model.
Vehicle (Part of ShipmentModel)	breakRule	object (BreakRule)	Defines rules for breaks (e.g., mandatory lunch break).
	costPerHour	number	Cost per hour of the total route duration.
	costPerKilometer	number	Cost per kilometer traveled.
	costPerTraveledHour	number	Cost per hour while the vehicle is moving.
	endLocation	object (LatLng)	The geographic end location as latitude/longitude coordinates.
	endTags[]	array of strings	Tags defining the vehicle's end state, used for transition attributes.
	endTimeWindows[]	array of objects (TimeWindow)	Allowed windows for the vehicle to end its route.
	endWaypoint	object (Waypoint)	Geographic end location using a Waypoint (coordinates or place ID).
	extraVisitDurationForVisitType	map (key: string, value: Duration)	Adds extra duration to visits based on their visitType.
	fixedCost	number	A fixed cost that's applied if the vehicle is used, regardless of the route's distance or duration.
	ignore	boolean (true/false)	If true, the vehicle is ignored and not used in optimization.
	label	string	User-defined label for the vehicle, returned in the response.
	loadLimits	map (key: string, value: LoadLimit)	Vehicle capacities (e.g., max weight, max volume).
	routeDistanceLimit	object (DistanceLimit)	A hard or soft limit on the total distance of the vehicle's route.
	routeDurationLimit	object (DurationLimit)	A hard or soft limit on the total duration of the vehicle's route.
	routeModifiers	object (RouteModifiers)	One or several constraints like avoiding tolls, highways, or ferries.
	startLocation	object (LatLng)	The geographic start location as latitude/longitude coordinates.
	startTags[]	array of strings	Tags defining the vehicle's start state, used for transition attributes.
	startTimeWindows[]	array of objects (TimeWindow)	Allowed windows for the vehicle to start its route.
	startWaypoint	object (Waypoint)	Geographic start location using a Waypoint (coordinates or place ID).
	travelDurationLimit	object (DurationLimit)	A hard or soft limit on the total travel duration (excluding wait/service time) of the vehicle.
	travelDurationMultiple	number	Multiplier applied to travel times (e.g., 1.5 makes travel 50% slower).
	travelMode	enum (TravelMode)	The travel mode (e.g., DRIVING, WALKING). Affects travel times and distances.
	unloadingPolicy	enum (UnloadingPolicy)	Defines order of unloading (e.g., LIFO or LAST_IN_FIRST_OUT).
	usedIfRouteIsEmpty	boolean (true/false)	If true, the vehicle is considered used even without shipments. It incurs fixed costs and travels between its start and end locations.

Response body

The response body includes the following elements, which are illustrated in the diagram to the right and listed in the table below:

• OptimizeToursResponse: The top-level response object that contains the optimized routes and metrics.
  • Metrics: The overall cost and execution statistics for the solution.
  • ShipmentRoute: The sequence of visits and travel path assigned to a single vehicle.
    • Visit: A stop on a route to perform a pickup or delivery.
    • Transition: The travel path and duration between two route stops.
    • AggregatedMetrics: The summed totals for duration, distance, and other metrics. This element can be present both in Metrics and ShipmentRoute.

Parent	Parameter	Property type	Description
OptimizeToursResponse	metrics	object (Metrics)	Aggregated metrics for the solution, including total cost, total distance, total duration, and vehicle usage counts.
	requestLabel	string	The label copied from the request's label field. Used to correlate the response with the original request.
	routes[]	array of objects (ShipmentRoute)	The list of routes calculated for each vehicle. Contains an entry for every vehicle, regardless of usage.
	skippedShipments[]	array of objects (SkippedShipment)	The list of shipments that were skipped (not serviced), along with the reasons they were skipped.
	validationErrors[]	array of objects (OptimizeToursValidationError)	A list of validation errors found in the input model. This is populated if the solvingMode was set to VALIDATE_ONLY, or if errors occurred during solving.
Metrics (Part of OptimizeToursResponse)	aggregatedRouteMetrics	object (AggregatedMetrics)	Aggregated statistics across all routes, such as total travel distance, total duration, and wait times.
	costs	map (key: string, value: number)	A breakdown of costs by type (e.g., "model.vehicles.cost_per_kilometer", "model.shipments.penalty_cost").
	earliestVehicleStartTime	Timestamp	The earliest start time among all used vehicles.
	latestVehicleEndTime	Timestamp	The latest end time among all used vehicles.
	skippedMandatoryShipmentCount	integer	The number of mandatory shipments that were skipped.
	totalCost	number	The total cost of the solution, summing all route costs and skipped shipment penalties.
	usedVehicleCount	integer	The number of vehicles used in the solution.
AggregatedMetrics (Part of Metrics and ShipmentRoute)	breakDuration	Duration	The total duration of breaks taken across all routes.
	costs	map (key: string, value: number)	A breakdown of costs by type (e.g., "model.vehicles.cost_per_kilometer", "model.shipments.penalty_cost").
	delayDuration	Duration	The total delay duration across all routes.
	earliestVehicleStartTime	Timestamp	The earliest start time among all used vehicles.
	latestVehicleEndTime	Timestamp	The latest end time among all used vehicles.
	maxLoads	map (key: string, value: VehicleLoad)	The maximum load carried by any vehicle at any point in the solution, keyed by the load type.
	performedShipmentCount	integer	The total number of shipments performed across all vehicles.
	skippedMandatoryShipmentCount	integer	The number of mandatory shipments that were skipped.
	totalCost	number	The total cost of the solution, summing all route costs and skipped shipment penalties.
	totalDuration	Duration	The total duration of all routes (travel + wait + delay + break + visit).
	travelDistanceMeters	number	The total travel distance in meters across all routes.
	travelDuration	Duration	The total travel duration across all routes.
	usedVehicleCount	integer	The number of vehicles used in the solution.
	visitDuration	Duration	The total duration spent performing visits (loading/unloading) across all routes.
	waitDuration	Duration	The total wait duration across all routes.
ShipmentRoute (Part of OptimizeToursResponse)	breaks[]	array of objects (Break)	A list of breaks taken by the vehicle during the route.
	hasTrafficInfeasibilities	boolean (true/false)	Indicates if the route has any traffic-related infeasibilities.
	metrics	object (AggregatedMetrics)	Metrics specific to this route, such as the total distance and duration traveled.
	routeCosts	map (key: string, value: number)	A breakdown of costs for this route. Keys are cost types (e.g., "cost_per_hour"), and values are the amounts.
	routePolyline	object (EncodedPolyline)	The encoded polyline representing the full path of the route geographically.
	routeTotalCost	number	The total cost of the route, sum of all costs in the routeCosts map.
	transitions[]	array of objects (Transition)	An ordered list of transitions (travel legs) connecting the visits.
	vehicleEndTime	Timestamp	The time at which the vehicle finishes its route.
	vehicleIndex	integer	The index of the vehicle in the source ShipmentModel that performs this route.
	vehicleLabel	string	The user-defined label of the vehicle, copied from the request model.
	vehicleStartTime	Timestamp	The time at which the vehicle starts its route.
	visits[]	array of objects (Visit)	The ordered sequence of visits (pickups and deliveries) performed by the vehicle on this route.
Visit (Part of ShipmentRoute)	detour	Duration	The extra detour time incurred by this visit compared to the direct path between the previous and next visits.
	isPickup	boolean (true/false)	If true, this visit is a pickup. If false, it is a delivery.
	loadDemands	map (key: string, value: Load)	The load demands satisfied by this visit (e.g. -1 for a delivery). This is a copy of the corresponding VisitRequest load demands.
	shipmentIndex	integer	The index of the Shipment field in the source model that this visit services.
	shipmentLabel	string	The label of the shipment, copied from the ShipmentModel.
	startTime	Timestamp	The time at which the visit is scheduled to start.
	visitLabel	string	The label of the visit request, copied from the VisitRequest in the model.
	visitRequestIndex	integer	The index of the VisitRequest in the shipment's pickup or delivery list that this visit corresponds to.
Transition (Part of ShipmentRoute)	breakDuration	Duration	The duration of breaks taken during this transition.
	delayDuration	Duration	The duration of delay incurred during this transition (e.g., arriving early and waiting for a time window).
	routePolyline	object (EncodedPolyline)	The encoded polyline representing the path of this specific transition.
	routeToken	string	An opaque token that can be passed to the Google Navigation SDK to reconstruct the route during navigation.
	startTime	Timestamp	The start time of this transition.
	totalDuration	Duration	The total duration of the transition, including travel, wait, breaks, and delays.
	trafficInfoUnavailable	boolean (true/false)	If true, indicates that traffic data was not available for this transition.
	travelDistanceMeters	number	The distance traveled during this transition, in meters.
	travelDuration	Duration	The duration of travel during this transition.
	vehicleLoads	map (key: string, value: VehicleLoad)	The load carried by the vehicle during this transition, keyed by the load type (e.g., "weight").
	waitDuration	Duration	The duration spent waiting before the next visit can start.