objectives list isn’t a set of weights. It’s a ranking: the engine compares two candidate solutions one objective at a time, in the order you give, and the first objective that separates them decides which one wins. This page explains that comparison, what each objective measures, and how to choose an order for your own operation.
How two solutions are compared
The engine looks at the first objective in the list. If one solution is better on it, that solution wins — whatever happens on every later objective. Only when the two solutions are tied on the first objective does the engine look at the second, and so on down the list. A tie means exactly equal values, with no tolerance. Even a very small difference decides. No amount of improvement on a later objective can make up for a loss on an earlier one. There are no weights to tune and no exchange rate between objectives: the position in the list is the only lever. So an objective measured in time, distance, or money hands over to the next one only when two solutions are exactly equal on it. The objectives after it only break ties. They aren’t secondary goals. One check comes even before the first objective. The engine prefers the solution that breaks fewer rules, whatever its objective values. See Hard vs soft constraints. Take three candidate solutions for the same plan:
With the default order (
maximizeMandatoryStops, then minimizeDelay, then … minimizeResources):
- C loses straight away: it plans one mandatory stop fewer, even though it’s better on every other line.
- A and B tie on mandatory stops, so delay decides: B wins, even though it needs an extra vehicle.
minimizeResources ahead of minimizeDelay and A beats B instead: you’ve told the engine that fleet size matters more than on-time delivery, so it lets stops run late to avoid dispatching an extra vehicle. C still loses under both orders, because maximizeMandatoryStops stays first.
Objectives split by priority
Three objectives depend onpriority: maximizeMandatoryStops and maximizeOptionalStops (from each order’s priority) and minimizeResources (from each resource’s priority). For these, the engine generates one objective per priority value present in the plan, and keeps them at the position of the original objective in the list. Lower numbers matter more, and negative values are allowed.
- Stops are maximized from the most important level down. With mandatory stops at priorities
0and1,maximizeMandatoryStopsbecomes two successive objectives: first maximize the priority-0mandatory stops, then the priority-1ones. One more planned priority-0stop always wins over any number of priority-1stops: priority levels are strict tiers, not weights. - Resources are minimized from the least important level up. With resources at priorities
0,1, and2,minimizeResourcesfirst minimizes the priority-2resources in use, then the priority-1ones, then the priority-0ones — so the least important resources are the first left unused.
The default list
If a plan doesn’t setobjectives, the engine uses this order:
overlappingCapacitiesByStopTag limits; then more optional stops; then more stops matched to a resource’s preferredStopTags; then less total working time; then less distance.
Treat it as a starting point to check against your plan, not a template to copy. Several entries do nothing unless your plan declares the data they measure (see each objective below), and an objective your operation cares about may be missing from it.
Rules for the list
- The list is used as you write it. The default list applies only when
objectivesis omitted or empty ([]). Once you set the list, the engine adds nothing to it. An objective you leave out isn’t optimized. No error or warning tells you so. The one exception isminimizeEarlyLoadings, covered below. - Keep
maximizeMandatoryStopsin it. A list without it is accepted, but then nothing rewards the engine for planning a stop. For example, with"objectives": ["minimizeDistance"]alone, the engine plans no stop at all. Every stop then ends up inunaffectedStopIds. - Each entry appears once. A list with two entries of the same name is refused with a
400ID_NOT_UNIQUEerror onplan.objectives. The error names the repeated entry. This rule also covers twomaximizePrecedencesobjects, even with different pairs, and twocustomentries with the samename. minimizeEarlyLoadingsand its declarations go together. See minimizeEarlyLoadings.
Built-in objectives
Each built-in objective is a plain string in the list. Some of them only apply when the plan declares the data they measure. Otherwise, they are ignored without error and left out of the solution’sobjectives. The section of each objective says when it applies. Remove from the list the objectives your plan declares no data for: they have no effect.
maximizeMandatoryStops
Maximizes the number of mandatory (non-optional) stops planned. It comes first in the default list, so the engine never leaves a mandatory stop unplanned to improve a later objective such as delay, cost, or distance. A mandatory stop goes unplanned only when the engine finds no valid tour for it. Orders can carry apriority. It’s an integer, 0 by default, where a lower number is more important and negative values are allowed. The objective takes the priority levels one at a time, most important first. It plans as many stops as possible at the first level, then at the next, and so on. One more planned stop at an important level always beats any number of stops at a less important one — see Objectives split by priority. A low priority doesn’t make an order optional: only "optional": true does that (see maximizeOptionalStops).
Set priority and optional on the order. They apply to every stop it contains — see Order, stop.
minimizeDelay
Minimizes the sum of the delays of all stops. A stop’s delay is the time between the end of itspreferredTimeWindows and the start of service at the stop, when service starts after the window. The value is in hours. Only lateness counts: the engine never starts service before a preferred window opens, so there is no early arrival to penalize.
Without any preferredTimeWindows, there is no delay to measure. The objective then stays in the list and in the solution’s objectives, with a value of 0. This is also the case for a plan whose windows are all hard authorizedTimeWindows — see Hard vs soft constraints.
minimizeCosts
Minimizes the plan’s total cost, which is the sum of the costs of all tours. Each tour’s cost comes from its resource’scost object. That object can charge for using the resource (using), per kilometre travelled (km), per hour worked (workedHours), or per unit of capacity. See The cost object for every option.
This objective only applies if at least one resource has a non-empty cost. Otherwise, it is ignored and left out of the solution’s objectives.
minimizeResources
Minimizes the number of resources used. Resources can carry apriority. It’s an integer, 0 by default, where a lower number is more important and negative values are allowed. The objective takes the priority levels one at a time, starting with the least important (highest number). It first uses as few resources as possible at that level, then at the next level up. The least important resources are therefore the first left unused — see Objectives split by priority.
No cost needs to be defined for this objective to work: it directly minimizes the number of resources, per priority level.
minimizeOverOverlappingCapacitiesOnStops
Minimizes the number of resources present beyond the limits set inoverlappingCapacitiesByStopTag. Each limit caps how many resources can be at stops sharing a tag at the same time, for example the loading docks of a depot. See Limiting simultaneous depot visits.
These limits are soft constraints: the engine exceeds them only to improve an objective ranked before this one.
This objective only applies if the plan sets overlappingCapacitiesByStopTag. Otherwise, it is ignored and left out of the solution’s objectives.
maximizeOptionalStops
Maximizes the number of optional stops planned, in addition to the mandatory ones. Optional stops are those of the orders marked"optional": true. As for maximizeMandatoryStops, the priority levels are taken one at a time, most important first — see Objectives split by priority.
This objective is the only reason the engine plans an optional stop. Such a stop adds distance and time without serving any other objective. So without maximizeOptionalStops in the list, it is unlikely to be planned at all.
In the default order it comes after minimizeResources, so the engine never adds a vehicle just to plan an optional stop.
This objective only applies if at least one order is marked "optional": true. Otherwise, it is ignored and left out of the solution’s objectives.
maximizePreferredStops
Maximizes the number of stops served by a resource that prefers them. A resource prefers the stops that carry one of itspreferredStopTags — see Skills and assignments.
This preference is a soft constraint: another resource can still serve the stop, but only to improve an objective ranked before this one.
This objective only applies if at least one stop carries one of the resources’ preferredStopTags. Otherwise, it is ignored and left out of the solution’s objectives.
minimizeLargestTourDuration
Minimizes the working duration of the longest tour of the fleet, travel, service, and waiting time included. This helps balance the workload between resources. It isn’t in the default list: add it toobjectives to use it.
It reduces the longest tour as far as it can, but it isn’t a limit. For a hard limit on tour duration, use a resource’s maxWorkingDuration.
minimizeWorkingDuration
Minimizes the total working duration across all tours, travel, service, and waiting time included.minimizeDistance
Minimizes the total distance travelled across all tours.minimizeEarlyLoadings
Minimizes early loadings. It avoids loading goods too early when it can, for example when a resource visits the depot several times during its tour. An early loading happens when a vehicle loads an order at a stop with a declared tag, such as a depot, then comes back to a stop with that tag before delivering the order. The vehicle could have loaded the order on that later visit. The objective also tracks goods going the other way, such as returns brought back to a depot. The vehicle collects these goods elsewhere and unloads them at a stop with the tag. Every visit to a stop with the tag between the collection and the unloading counts against the objective. You declare the tags in one of two places. Per resource, useavoidEarlyLoadings. Per resource tag, use the plan-level avoidEarlyLoadingsByResourceTag, where the key "*" matches every resource. Each declaration names a stopTag, and optionally a list of capacities. With capacities, the engine tracks only the orders that load or unload one of these capacities at a stop with that tag. When capacities is empty or omitted, every capacity is tracked.
The objective counts passes. A pass is a visit to a stop with the tag. Several tagged stops in a row count as one pass. For each tracked order, the engine counts the passes between the moment the order is loaded and the moment it is delivered. The pass where the order is loaded or unloaded at a tagged stop counts too. The objective’s value is the sum over all tracked orders, a count with no unit. So an order loaded on the last pass before its delivery counts 1. The same goes for an order unloaded on the first pass after its loading. The lowest possible value is therefore the number of tracked orders, not 0.
The objective and the declarations go together. A plan with declarations but no minimizeEarlyLoadings in objectives is refused with a 400 INVALID_INPUT error. A plan with the objective but no declaration is refused in the same way. Omitting objectives doesn’t help, because the default list doesn’t contain minimizeEarlyLoadings. So when you declare early loadings, you need to write the whole list yourself.
Declarations can also track nothing. No error or warning tells you so, but two results in the solution show it. If the value of minimizeEarlyLoadings is 0, no order is tracked. Check the names in capacities. If minimizeEarlyLoadings is missing from the solution’s objectives, no declaration matched both a resource and a stop. In that case, check the stopTag, and the resource tags that you use as keys of avoidEarlyLoadingsByResourceTag.
minimizeEarlyLoadings added right after minimizeResources. At that position, the engine never accepts a higher cost or an extra vehicle to avoid an early loading. It only uses the objective to choose between solutions that are tied on every objective before it. If avoiding early loadings matters more to you than cost, move it before minimizeCosts.
Object entries
Two kinds of entries are objects rather than names.maximizePrecedences
Rewards the engine for respecting “this stop tag before that stop tag” rules. It takes aprecedences array of pairs, each with a previous and a next stop tag, and the engine tries to satisfy as many pairs as it can. It is a preference, not a hard rule: the engine may break a pair to do better on an objective ranked higher in the list, and it can still plan every stop. This objective only applies if at least one stop carries a tag named in a pair. Otherwise, it is ignored and left out of the solution’s objectives.
A pair only counts between stops of the same tour, and it looks at which stop comes first in the tour, not at the clock times. Two stops in two different tours never constrain each other. The objective can still favour more tours: ranked before minimizeResources, it can make the engine use more vehicles than it needs. For example, four stops that one vehicle could serve can end up split over two vehicles. Setting disableGroupProximity to true does not change this. Pairs chain: a before b and b before c ask for a, then b, then c. A loop of pairs, such as a before b, b before c and c before a, is refused with a 400 error.
By default, the engine adds a second objective right after maximizePrecedences. It groups the stops of the same sector in a tour, and by default it ranks before every objective you list after maximizePrecedences, including minimizeCosts and minimizeDistance. Set disableGroupProximity to true in the entry when you need the order of the pairs but not this grouping.
In the solution, maximizePrecedences shows up in objectives always with the direction maximize. By default there are two lines, maximizePrecedences(valid-precedences) and maximizePrecedences(valid-precedences-group-proximity). With disableGroupProximity set to true, there is one line, named maximizePrecedences.
For an order the engine always keeps, use the strict form instead: put the stops in one order’s stops array, and they are planned in that order, on one vehicle. See Hard vs soft constraints.
Custom objectives
Acustom entry optimizes a cost expression that you define, in the direction of your choice (minimize or maximize). The expression comes from costsByResourceTag. It gives a cost for each resource tag, in the same format as a resource’s cost object. That cost applies to the tours of the resources that carry the tag.
The name identifies the objective in the solution’s objectives. It must be different from the built-in objective names. As with every entry, each name may appear only once in the list (see Rules for the list).
When a custom objective replaces minimizeCosts, put it at the exact position minimizeCosts held. Anywhere else, it’s traded off against different objectives and can return a different plan. See Cost modeling for an example.
This objective only applies if at least one resource carries a tag named in costsByResourceTag. Otherwise, it is ignored and left out of the solution’s objectives.
Choosing an order
- Put first what you’d never trade away. For most operations that’s
maximizeMandatoryStops: no later objective can then make the engine drop a mandatory stop. Without it, the engine may plan no stop at all (see Rules for the list). - Check every adjacent pair, not just the first two. Swapping any two neighbours changes which solutions win.
minimizeCostsbeforeminimizeResourcesprioritizes total cost even if reaching it takes an extra vehicle; the reverse caps fleet size first and lets cost settle wherever that leaves it. - Drop the objectives your plan gives no data to, and add the ones it needs. For example, add
minimizeLargestTourDurationto balance tours. If you declare early loadings, you must addminimizeEarlyLoadings. - Keep preferences in objectives, rules in constraints. A hard constraint is never traded off, whatever the order; only soft constraints are arbitrated by the list. See Hard vs soft constraints.
Reading objectives in a solution
A solution reports the achieved value of each objective inobjectives, with its name, direction (minimize or maximize), and value. Values aren’t rounded. Durations are in decimal hours: 1.25 is 1 hour 15 minutes.
The three objectives split by priority have one entry per priority level, each with a
priority field giving the level it covers — a plan with mandatory stops at priorities 0 and 1 returns two maximizeMandatoryStops entries. Objectives removed for lack of data don’t appear. Comparing these values between two versions of a plan shows which objective an update actually moved.
See also
- How the optimization engine works — the time/quality trade-off and how updates re-optimize a plan.
- Hard vs soft constraints — what the objectives arbitrate, and what they never bend.
- Cost modeling — giving
minimizeCostsand custom objectives something to optimize. objectivesin the API reference — the field’s schema.

