How a solve works, end to end
Five stages carry a day's orders to an executable plan. Two more pipelines reuse the same stages: one re-plans when the day changes, and one scores a plan you already have.
Plan the day
Orders, fleet and rules go in. Routes on real roads come out, with the cost of every stop and the reason for every job that did not fit.
- 01Data collection
Gather what the planner already knows
- Orders. What moves, how much, from where to where.
- Locations. Each site with its coordinates.
- Fleet. Vehicles, capacities, where shifts start and end.
- Time windows. When each site will accept a visit.
- Costs. Per kilometre, per hour, per vehicle used.
- Driver rules. Breaks and limits on driving and working time.
Distances and travel times are not on the list. The road network is built into the engine.
- 02Problem specification
Write the day as a model
Your software fills one schema. Distance, time and capacity are all
dimensions, so a new measure such as pallets or litres is another dimension, not a new feature.The schema is protobuf, so a missing required field fails on your side before anything is sent.
Model { dimensions // distance, time, capacity locations // where things happen jobs // pickup and drop-off tasks vehicles // what is being scheduled vehicleClasses // how vehicles move vehicleCostClasses // how vehicles are costed transitRules // fatigue breaks compartments // IVR8 only } - 03Solver request
Post the model, get a request id
The model goes inside a solve request, and the solve request inside an envelope that names the schema. The envelope is the HTTP body.
The POST does not wait for the solve. It returns a request id straight away.
POST https://api.icepack.ai/vehicle-router/solve/ Authorization: Apitoken <token> Content-Type: application/protobuf ProblemEnvelope { type: "ivr7-kt461v8eoaif" subType: INPUT content: SolveRequest { model: { ... } solveType: Optimise } } → request id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx - 04Solver response
Ask for the result until it is complete
Each GET holds open for up to 30 seconds waiting for news from the solver. Repeat it until
stateisCOMPLETED.Results stay available for 24 hours under the same request id.
GET https://api.icepack.ai/vehicle-router/solve/{requestid} SolverResponse { state: WIP | COMPLETED | FAILED logs: [ INFO | WARNING | ERROR ] solution: SolutionResponse { objective // total cost of the plan routes // vehicleId, stops, interStops infeasibilities // jobs left out, and why } } - 05Display and analysis
Put the routes back in your own screens
- Schedule. Every stop carries its start and end value, cost, slack and lateness for each dimension.
- Map. Each leg carries
routeSegments, the road path as a line of coordinates. - Cost.
objectiveis the running cost of every route plus the fixed cost of every vehicle used. - Exceptions. Each job left out names the rule, the limit and the value that broke it.
Re-plan mid-shift
The plan on the road becomes the starting point. The engine improves it around what has changed.
- 01The day changes
Something happens after dispatch
- A new order arrives.
- A customer cancels or moves a window.
- A vehicle runs late or drops out.
- 02Problem specification
Change only what changed
Send the model again with the change applied. If the model itself is unchanged, refer to the earlier solve by its request id as
modelId. Models stay in the cache for 24 hours. - 03Solver request
Send the routes as they stand
Each vehicle's current run goes in as a task sequence. The engine uses those routes as its starting solution and keeps optimising from there.
Same endpoint, same envelope. Only the solve request differs.
SolveRequest { model: { ...with the change applied... } // or modelId: "<earlier request id>" routes: [ TaskSequence { vehicleId, taskId[] } // one per vehicle ] solveType: ReOptimise } - 04Solver response
The same response, usually in under a second
The shape is identical to a full solve. When the routes you sent were feasible, the result is never worse in cost than what you sent.
- 05Display and analysis
Show what moved
Your system compares the new routes with the ones on the road and sends drivers only the stops that changed. Then the loop is ready for the next change.
Score an existing plan
The engine does not plan anything. It takes a plan made elsewhere, costs it on the same cost model, and lists every rule it breaks.
- 01Data collection
The same data, plus the plan itself
Everything a full solve needs: orders, locations, fleet, windows, costs and driver rules. Then the plan as it was made: for each vehicle, the tasks it did, in order.
The plan can come from a TMS export, a planner's spreadsheet or a carrier's manifest.
- 02Problem specification
One model, one task sequence per vehicle
The model is built exactly as for a full solve, so the plan is judged on the rules and costs you would give the engine. Vehicles that did not run are left out.
- 03Solver request
Send the plan as the routes
Same endpoint, same envelope. The routes are evaluated exactly as given and one solution comes back.
A planner's drag-and-drop edit can be scored the same way, against the model of the original solve.
SolveRequest { model: { ...orders, fleet, rules... } routes: [ TaskSequence { vehicleId, taskId[] } // the plan ] solveType: Evaluate } - 04Solver response
A cost, and every broken rule
The plan comes back timed and costed stop by stop. Each rule it breaks is reported at the task where it breaks, with the limit, the actual value and the tasks that caused it.
SolutionResponse { objective // what this plan costs routes // the plan, timed and costed infeasibilities: [ { taskId, infeasibilityInfo: [ { message, dimId, limit, value, constrainingTaskIds } ] } ] } - 05Display and analysis
Then solve the same model, and read the gap
- The gap. Run Optimise on the same model. Same orders, same fleet, same cost model: the difference between the two objectives is what the plan left on the table.
- The rule list. Group the broken rules by vehicle, planner, depot or carrier.
- Over time. Score every week and the result becomes a quality measure for planners, tools and subcontractors.
What changes between the three
| Pipeline | You send | The engine | You get back | Typical time |
|---|---|---|---|---|
| Optimise | The model | Builds the plan from nothing | Routes, cost, jobs left out | 0.77 s median, all solves |
| ReOptimise | The model and the routes on the road | Starts from your routes and improves them | Routes no worse than you sent | 0.3 s median |
| Evaluate | The model and a plan made elsewhere | Costs the plan as given | Cost and every broken rule | 0.13 s median |
Field names and endpoints are from docs.icepack.ai.
Timings are production usage, January 2025 to October 2026, as published at icepack.ai/performance: 0.77 s across 408,480 requests, 0.3 s for mid-shift re-optimisation, 0.13 s across more than 11,000 scored plans.