V3 is in beta. General availability (GA) is planned for 1 December 2026.
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 withdrop_cost: 6.r-return-mortsel, the return: apickup_loadof one parcel, 11:00 to 15:00.
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 toPOST /v3/routing/validate/solve first to check it without solving; the real call takes about five seconds of search plus the travel lookup.
- A standard slot and a premium slot are both
time_windowsentries. The only difference isper_late_houron the standard one. Omitting it makes a window hard; there is nohard: trueflag. Sendingper_late_hour: 0is a400. - The bike’s prices replace the fleet’s, field by field.
vehicles[].costsoncargo-bikesetsper_route: 25,per_route_hour: 22andper_travel_km: 0. A field left out of a vehicle’scostskeeps theobjective.costsvalue, so list every rate you mean to change. options.seed: 7fixes 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 dropslocation, 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
tasksreadsserved: 37, unassigned: 1, unassigned_required: 1. The unassigned task has nodrop_cost, so it counts as required. The call still returns HTTP200: 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[]listsvan-1andcargo-bike. A shift with no task stops gets noroutes[]entry at all, so a client that wants a line per vehicle has to fill invan-2itself.timeis summed over routes.travel_s21,198 s is driving only.depot_s1,200 s is the two ten-minute handling periods at the hub, which the bike’s micro-hub does not have because it sets noservice_duration_s.wait_s15,856 s is time spent arrived-but-early, 13,343 s of it on the bike.break_s1,800 s is van 1’s lunch.searchused 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 readsearch_progressand pick a budget.
Van 1, stop by stop
The route starts at the hub witharrival 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_sis 13,343 s over the route, in two blocks: it reachesp-centrum-05at 09:25 and the slot opens at 11:00, and it reachesp-centrum-06at 11:19 for a 13:00 slot. At 22 per hour, idling the bike is cheaper than sendingvan-1into the centre twice. The waiting shows up in the route’stime.span_s, and so in thetimecost component, not incomponents.waiting, which pricesper_wait_houronly. A carrier that would rather have the rider do something else between 09:30 and 11:00 splits the shift in two, or setsper_wait_hourso that the idle has a price of its own. - It stays far under its range.
limits.max_distance_m: 30000is a hard cap on the route’sdistance_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; compareroutes[].distance_mwith the limit yourself when you want to know a vehicle’s slack.
centrum. The vans could have taken centre parcels too, since they have no serves_tags; the bike won them on price.
The unassigned parcel
category: "blocked"says a vehicle could serve this address, but not in the window as given alongside the rest of the day. Moretime_limit_swould not help; a change to the input might.reasons[]lists one entry per rule that refused the task on some vehicle.serves_tagsis the bike: the parcel is taggedsuburband the bike servescentrum.time_windowis 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.relaxations[]quantifies it: a window 61 seconds longer would let the task in. Thepointeris a JSON Pointer into the request body,/problem/jobs/25/time_windows, so a client can find the field without matching on the id.
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 sameobjective.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: 180on 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 showswait_sper stop; a stretch with waits of zero everywhere has no slack, and onvan-1that 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
planobject in this response, with the stops already done insidelocked_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_timeasks for traffic-aware times at that moment instead. See Distance matrices.
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.