Icepack Routing engine
Vehicle routers · IVR7 and IVR8

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.

Existing planfrom your TMS or a carrier routes = the plan solveType: Evaluate Data collectionorders, fleet, rules Problem specificationthe day as a model Solver requestPOST, get a request id Solver responseGET until COMPLETED Display and analysismap, schedule, cost The day changesnew order, late vehicle routes = the plan on the road solveType: ReOptimise
Shown for the vehicle routers, IVR7 and IVR8. The other models use the same envelope with their own schemas.
solveType: Optimise

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.

  1. 01
    Data 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.

  2. 02
    Problem 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
    }
  3. 03
    Solver 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
  4. 04
    Solver 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 state is COMPLETED.

    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
      }
    }
  5. 05
    Display 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. objective is 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.
solveType: ReOptimise

Re-plan mid-shift

The plan on the road becomes the starting point. The engine improves it around what has changed.

  1. 01
    The day changes

    Something happens after dispatch

    • A new order arrives.
    • A customer cancels or moves a window.
    • A vehicle runs late or drops out.
  2. 02
    Problem 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.

  3. 03
    Solver 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
    }
  4. 04
    Solver 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.

  5. 05
    Display 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.

solveType: Evaluate

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.

  1. 01
    Data 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.

  2. 02
    Problem 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.

  3. 03
    Solver 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
    }
  4. 04
    Solver 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 } ] }
      ]
    }
  5. 05
    Display 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.
Side by side

What changes between the three

PipelineYou sendThe engineYou get backTypical time
OptimiseThe modelBuilds the plan from nothingRoutes, cost, jobs left out0.77 s median, all solves
ReOptimiseThe model and the routes on the roadStarts from your routes and improves themRoutes no worse than you sent0.3 s median
EvaluateThe model and a plan made elsewhereCosts the plan as givenCost and every broken rule0.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.