Skip to main content
V3 is in beta. General availability (GA) is planned for 1 December 2026.
A parcel carrier runs a suburban hub east of Antwerp and a micro-hub in the city centre. One Thursday it has 36 deliveries with two-hour slots promised to the recipients, one re-attempt of a parcel the recipient missed yesterday, and one return to collect. Eight of the slots are paid premium slots that must be kept. The rest are standard slots the carrier would rather keep, but may miss at a known cost. Two vans work from the hub. A cargo bike works from the micro-hub, only inside the centre, and only for a few hours. This page models that day, solves it with POST /v3/routing/solve, and reads the plan: which vehicle does what, where the 10-minute loading at the hub shows up, why the second van stays in, which standard slots were missed and what each cost, and the one premium slot that no vehicle could keep. The response is real output for the request shown. Yours can differ in the travel figures, if the road data has changed since, and in timings. Field service day walks a smaller plan and then reuses it with evaluate and suggest; this page stays with one solve and goes deeper into reading it.

The business rules

Everything else the carrier might say (“van 1 usually does the north”) is left out on purpose. A rule that is not a constraint of the operation should not be sent as one; see AI agents for the full list of things not to assume. Capacity is in parcels. The vans never get close to their 120, so capacity acts on the bike alone. Counting parcels rather than weight is enough here because the carrier packs by count; a fleet that mixes bulky and heavy items would declare parcels and weight as two dimensions on the same capacity and delivery_load objects.

The data

All times are local time on 12 November 2026, written with the +01:00 offset. Coordinates are [longitude, latitude]. The 38 tasks:
  • 28 standard deliveries, 1 to 4 parcels each, 3 minutes at the door, in two-hour slots between 09:00 and 15:00, each slot priced at 12 per hour late.
  • 8 premium deliveries with the same shape but a hard slot and priority: 10: Deurne 08:00 to 10:00, Borgerhout, Merksem and one centre address 09:00 to 11:00, Brasschaat and Kapellen 09:00 to 10:00, one centre address 13:00 to 15:00, and one in Kontich promised for 07:30 to 08:00.
  • p-retry-wilrijk, the re-attempt: any time between 09:00 and 15:00, optional with drop_cost: 6.
  • r-return-mortsel, the return: a pickup_load of one parcel, 11:00 to 15:00.
Eight centre addresses carry tags: ["centrum"], the other 30 tags: ["suburb"]. The vans have no serves_tags, so the tags do not restrict them; only the bike reads them.

The request

The complete body, as sent. Send it to POST /v3/routing/validate/solve first to check it without solving; the real call takes about five seconds of search plus the travel lookup.
Three things to notice before reading the answer:
  • A standard slot and a premium slot are both time_windows entries. The only difference is per_late_hour on the standard one. Omitting it makes a window hard; there is no hard: true flag. Sending per_late_hour: 0 is a 400.
  • The bike’s prices replace the fleet’s, field by field. vehicles[].costs on cargo-bike sets per_route: 25, per_route_hour: 22 and per_travel_km: 0. A field left out of a vehicle’s costs keeps the objective.costs value, so list every rate you mean to change.
  • options.seed: 7 fixes the random stream. Repeating the call with the same body and seed on the same road data returns the same plan; change the seed to get a different, equally valid one.

The response

The response below is the real output for that request, trimmed in three ways to keep it readable: each stop keeps its times, waits, lateness, travel and load and drops location, snapped_location and service_s; the top-level search_progress and warnings are left out; and plan, which repeats the routes in request shape, is shown whole because it is what you send back. Response times are in each shift’s own offset, +01:00, so they read as local time.

The plan in one paragraph

Two of the three vehicles go out. van-1 does a full day from the hub: 29 stops, 162 km, back at 15:22 and unloaded by 15:32. The bike does the eight centre stops in just under five hours and 13 km, well inside its 30 km range, and spends most of that time waiting for slots to open. van-2 has no route: once the solver had a plan that served every reachable suburb parcel with one van, opening the second van would have cost 60 for the day plus its hours, and the alternative, being late on five standard slots at 12 per hour, came to 29.43. Thirty-seven of the 38 tasks are served, 32 of them inside their slot. One premium parcel, the 07:30 to 08:00 slot in Kontich, is unassigned, and the response says by how much it misses. That trade is the one to pause on. The carrier priced a late standard slot at 12 per hour, and the solver took it at its word: the plan is late by 2 hours 27 minutes in total across five stops, one of them by 85 minutes, because that was cheaper than a second van. If that is not what the carrier meant, the price is wrong, not the plan. Doubling per_late_hour or lowering per_route on van-2 changes the answer; the sections below show where to read the effect.

Summary

  • tasks reads served: 37, unassigned: 1, unassigned_required: 1. The unassigned task has no drop_cost, so it counts as required. The call still returns HTTP 200: a plan that leaves tasks out is a successful response, and the status code says nothing about it. Check these three numbers before anything else.
  • vehicles_used: 2, shifts_used: 2. routes[] lists van-1 and cargo-bike. A shift with no task stops gets no routes[] entry at all, so a client that wants a line per vehicle has to fill in van-2 itself.
  • time is summed over routes. travel_s 21,198 s is driving only. depot_s 1,200 s is the two ten-minute handling periods at the hub, which the bike’s micro-hub does not have because it sets no service_duration_s. wait_s 15,856 s is time spent arrived-but-early, 13,343 s of it on the bike. break_s 1,800 s is van 1’s lunch.
  • search used the five-second budget in full (termination: "time_limit") over 8,503 iterations. A plan this size is far from converged in five seconds; Performance explains how to read search_progress and pick a budget.

Van 1, stop by stop

The route starts at the hub with arrival and departure ten minutes apart: that is depots[].service_duration_s applied at start. load_after on the start stop is 46, the sum of the delivery_load of every delivery on the route, and load_peak is also 46: a delivery route is fullest when it leaves. Five moments on this route are worth tracing, in local time with the seconds dropped: Between those, the pattern is geographic: north in the morning, south-west around midday, north-east after lunch, south at the end. r-return-mortsel is the one stop where load_after goes up, from 6 to 7: a pickup_load is collected and ridden back to the hub, where load_after on the end stop is 1, the one parcel still on board for the return to the warehouse. Five stops carry a non-zero lateness_s: Hoboken, Ekeren, Brasschaat, Mortsel and Wilrijk, 8,829 s between them. Every one of them is a standard slot. A premium slot cannot be late, because its window has no price, and every premium stop on the route has lateness_s: 0. That is the field to assert on: a client that only reads summary.score.violation_count sees 0 here and learns nothing about the late stops, because priced lateness is a cost, not a violation.

The bike

cargo-bike leaves the micro-hub at 08:30 with ten parcels, serves the eight centrum addresses, and is back at 13:25 after 13.2 km. Two things in this route are the solver’s doing and worth understanding:
  • It waits more than it rides. wait_s is 13,343 s over the route, in two blocks: it reaches p-centrum-05 at 09:25 and the slot opens at 11:00, and it reaches p-centrum-06 at 11:19 for a 13:00 slot. At 22 per hour, idling the bike is cheaper than sending van-1 into the centre twice. The waiting shows up in the route’s time.span_s, and so in the time cost component, not in components.waiting, which prices per_wait_hour only. A carrier that would rather have the rider do something else between 09:30 and 11:00 splits the shift in two, or sets per_wait_hour so that the idle has a price of its own.
  • It stays far under its range. limits.max_distance_m: 30000 is a hard cap on the route’s distance_m, return to the micro-hub included; 13,224 m uses less than half of it. The response does not say how close a route came to a cap; compare routes[].distance_m with the limit yourself when you want to know a vehicle’s slack.
Every stop on the bike’s route is a job tagged centrum. The vans could have taken centre parcels too, since they have no serves_tags; the bike won them on price.

The unassigned parcel

Read it from the outside in:
  1. category: "blocked" says a vehicle could serve this address, but not in the window as given alongside the rest of the day. More time_limit_s would not help; a change to the input might.
  2. reasons[] lists one entry per rule that refused the task on some vehicle. serves_tags is the bike: the parcel is tagged suburb and the bike serves centrum. time_window is the vans: the slot is 07:30 to 08:00, the shifts start at 07:30 and loading at the hub takes ten minutes, so no van leaves before 07:40, and Kontich is about 21 minutes away. The slot was promised for a time before any vehicle could get there.
  3. relaxations[] quantifies it: a window 61 seconds longer would let the task in. The pointer is a JSON Pointer into the request body, /problem/jobs/25/time_windows, so a client can find the field without matching on the id.
The fix is a business decision, not a solver setting: tell the recipient 08:00 to 08:30, cut the hub loading time, or start the shift earlier. What the response does not offer is to be a minute late on its own: the premium window has no per_late_hour, so lateness is not for sale on it, and the parcel is left out rather than delivered late. That is the behaviour the carrier asked for when it called the slot a contract.

Score

score.cost is the sum of score.components, in the currency you labelled: unassigned_priority is 10: the priority of p-kontich-03, the one required task left out. On a plan that leaves several tasks out this number is what the solver minimised first, before cost, so two plans with the same unassigned count are ranked by whose priorities they dropped. The drop_cost on p-retry-wilrijk never came into play: the address sits between two other Wilrijk stops, so serving it cost less than 6.

One KPI line

Cost per served stop: 13.44 (497.30 over 37 stops), with 32 of 37 slots kept, 2 hours 27 minutes of lateness across the other five at a cost of 29.43, and one premium slot unserved. Track that number across days with the same objective.costs; it moves when the geography, the slot mix or the fleet changes, and it is comparable between plans only while the prices stay the same.

What the solution cannot prove

The response proves what the solver was told to respect. It cannot prove what it was not told:
  • That 12 per hour is what a missed slot costs. The plan is the cheapest one under the prices sent. Five late stops and an idle second van is the right answer at 12 per hour and the wrong one at 40. The response cannot tell you which price is true; only the business can.
  • That the slots are the ones promised. A window is read as sent. A slot typed as 13:00 to 15:00 for a parcel promised 15:00 to 17:00 is kept perfectly and still disappoints the recipient. Nothing in the response can detect that.
  • That three minutes at the door is right. service_duration_s: 180 on every delivery is an average. A route planned on averages is early at some doors and late at others, and a plan with no slack in it turns small overruns into misses. The response shows wait_s per stop; a stretch with waits of zero everywhere has no slack, and on van-1 that is the whole route after 09:03.
  • That the plan survives the morning. It is a plan for 07:30. A re-attempt that turns up, a van that leaves late or a closed road all call for a re-plan from the plan object in this response, with the stops already done inside locked_count. See Re-optimization.
  • That the road data matches the day. Travel times here are free-flow times from the default engine. A morning in Antwerp traffic is slower; travel.departure_time asks for traffic-aware times at that moment instead. See Distance matrices.
What it does prove, and how to check it in code: every stop’s service_start lies inside its window or carries lateness_s; every premium stop has lateness_s: 0; every stop on the bike’s route belongs to a job tagged centrum; the bike’s distance_m is under 30,000; each route’s load_peak is within its vehicle’s capacity; and every task is either in some route’s stops or in unassigned[]. Those are the assertions worth writing into a test against this response. Constraints ends each rule with the field that proves it held.

Next steps

Field service day

The same loop on a smaller plan, then evaluate and suggest.

Re-optimization

Re-plan from this response’s plan when the morning changes.

Handling infeasibility

Reading categories, reasons and relaxations, and the ranked fixes.

Objective function

Every cost component and the V3 defaults.