What it does
You give the optimiser a day’s work and the resources available to cover it. It gives you back a set of runs that can actually be driven.
- Stop sequencing. The order each driver visits their stops in, chosen to minimise whichever objective you pick — total distance, total time, or total cost.
- Assignment. Which driver and which vehicle each run belongs to, drawn from the drivers and vehicles you have marked as available for that date.
- Capacity awareness. Weight, volume and item counts are treated as hard limits, not warnings. A vehicle is never given more than it can carry.
- Time windows. A stop that can only be served between 9am and noon is sequenced to land in that window, or is left unassigned and reported — never quietly scheduled for 4pm.
- Shifts and breaks. Driver working hours and mandated rest breaks are part of the plan, so a run does not depend on someone skipping lunch.
- Skills and certifications. A stop that needs a refrigerated vehicle, a dangerous-goods licence, or a specific qualification only goes to a driver who has it.
- Multiple depots. Runs can start and finish at different locations rather than assuming one hub.
- Re-optimisation. When the day changes — a stop cancels, an urgent job lands, a driver goes offline — you can re-solve the affected part without discarding the plan.
How it works
Your plan is solved on its own
The unit of optimisation is your account. Your stops, vehicles, drivers and constraints are never considered alongside anyone else’s, and a large plan running for another customer does not slow yours down or change its result. A plan you solve twice with the same inputs gives you the same answer.
Constraints come first, not last
A naive optimiser builds a cheap-looking plan and then tries to repair the parts that break your rules. This one rejects an invalid move while the plan is being built. The practical consequence is that you do not receive plans that look excellent on paper and fall apart on the road — if a stop could not be served within its window by any available driver, it comes back to you as unassigned with the reason, rather than assigned to someone who cannot make it.
Real roads, not straight lines
Travel time and distance between every pair of points come from the platform’s own road-network service, so a plan reflects how vehicles actually drive — one-way streets, turn restrictions, road classes — rather than how far apart two pins look on a map. This matters more than it sounds: a plan built on straight-line distance routinely under-estimates a dense urban run by a third.
Changes are incremental
Once a day is under way, re-planning from scratch is disruptive — drivers have already been briefed and are already moving. Re-optimisation adjusts the runs affected by the change and leaves the rest alone, so adding one urgent job does not reshuffle every other driver’s afternoon.
Permissions
Optimisation reads the work and the resources, and writes back the resulting runs and stop assignments. These are the permissions to attach to the credential your integration uses.
| Permission | What it allows | Needed |
|---|---|---|
| stops.read | Read the stops being planned — locations, timings, capacities and package linkages. | Required |
| stops.write | Write the assignment of a stop to a run once the plan is produced. | Required |
| runs.read | Read runs, their stop sequencing and their metrics. | Required |
| runs.write | Create runs and write their sequencing and dispatch records. | Required |
| drivers.read | Read driver records, vehicle assignments and availability for the date being planned. | Required |
| assets.read | Read the vehicles and trailers available, including their capacity attributes. | Required |
| service-areas.read | Restrict candidate drivers to the regions they are eligible to cover. | Optional |
| run-schedules.read | Seed a plan from a recurring run-schedule template rather than a blank day. | Optional |
API reference
The optimiser has no public contract of its own yet. Sequencing and dispatch live on the core runs API, which is where an optimised trip lands once the module ships.
| Service | What it covers | Reference | Contract |
|---|---|---|---|
| runs-api | Runs, stop sequencing and dispatch. Core platform — callable without this module. | OpenAPI description | openapi.json |
The contract above belongs to the core platform, not to this module. It is listed because it is the surface that does this work today — when the module publishes its own API, it will appear here.
Each openapi.json is the generated OpenAPI 3.1 contract, served by the service itself — it is never hand-edited, so it cannot drift from the running API. The OpenAPI description link opens the same contract as a browsable reference. Both resolve to the environment these docs are served from, so a page read on the test site links to the test contract.
Events
Optimising a day produces runs, and those runs move through their lifecycle on the event stream. Subscribe to these rather than polling for a plan to appear.
| Event | Raised when | Tells you |
|---|---|---|
| run.created | The optimiser produces a new run for a driver and date. | The run identifier, the date, and the driver and vehicle it was built for. |
| run.assigned | A run is attached to a driver and/or vehicle. | Which driver and vehicle took the run, and when. |
| run.reordered | The stop order on a run changes — including from a re-optimisation. | The full new stop order, so you can recalculate arrival estimates without re-reading the run. |
| stop.assigned | A stop is placed onto a run by the plan. | Which run and driver the stop landed on. |
| run.status.changed | The run moves through its lifecycle. | The status it moved from and the status it moved to. |
| run.started | The driver starts the run. | The driver and the start time — the point a plan becomes an execution. |
| run.completed | The run reaches its terminal completed state. | The driver and the completion time. |
| run.cancelled | The run is cancelled before completion. | When it was cancelled. |
| break.started | A driver begins a break the plan allowed for. | The break and run identifiers, and the driver. |
| break.completed | A driver finishes a break. | The break and run identifiers, and the completion time. |
The surrounding surfaces — runs, stops, drivers, vehicles — and the run lifecycle events above are part of the base platform and behave as described. The optimiser itself is designed but not yet callable; enabling this module today registers your interest and does not change platform behaviour.
The envelope these arrive in, the delivery and retry guarantees, and every other event type are in Events & webhooks — or jump straight to the event catalog.