Skip to main content
A plan’s 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.
Move 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 on priority: 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 0 and 1, maximizeMandatoryStops becomes two successive objectives: first maximize the priority-0 mandatory stops, then the priority-1 ones. One more planned priority-0 stop always wins over any number of priority-1 stops: priority levels are strict tiers, not weights.
  • Resources are minimized from the least important level up. With resources at priorities 0, 1, and 2, minimizeResources first minimizes the priority-2 resources in use, then the priority-1 ones, then the priority-0 ones — so the least important resources are the first left unused.

The default list

If a plan doesn’t set objectives, the engine uses this order:
In plain terms: first plan as many mandatory stops as possible; among solutions that do, prefer less customer delay; then lower cost; then fewer vehicles; then fewer breaches of 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 objectives is 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 is minimizeEarlyLoadings, covered below.
  • Keep maximizeMandatoryStops in 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 in unaffectedStopIds.
  • Each entry appears once. A list with two entries of the same name is refused with a 400 ID_NOT_UNIQUE error on plan.objectives. The error names the repeated entry. This rule also covers two maximizePrecedences objects, even with different pairs, and two custom entries with the same name.
  • minimizeEarlyLoadings and 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’s objectives. 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 a priority. 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 its preferredTimeWindows 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’s cost 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 a priority. 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 in overlappingCapacitiesByStopTag. 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 its preferredStopTags — 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 to objectives 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, use avoidEarlyLoadings. 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.
This is the default list, with 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 a precedences 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

A custom 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. minimizeCosts before minimizeResources prioritizes 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 minimizeLargestTourDuration to balance tours. If you declare early loadings, you must add minimizeEarlyLoadings.
  • 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 in objectives, 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