Suggest

V3 is in beta. General availability (GA) is planned for January 2027.

Overview

POST /v3/routing/suggest answers one question: given the plan I already have, where can this new task go, and what does each insertion cost? You send the same body as /v3/routing/evaluate: the problem and the plan you have committed to. Every task of the problem that is not in the plan is a task to place, and for each one you get back a ranked list of feasible insertion positions, best first. Use it when a new order arrives during the day and a dispatcher (or your own code) should pick a slot, rather than letting the solver rearrange routes that are already on the road. The committed plan is never changed: the API holds no state, so nothing happens until you apply an insertion yourself.

You want to	Use
Build or rebuild routes	`/v3/routing/solve`
Score a plan you already have	`/v3/routing/evaluate`
Find slots for new tasks in a plan you keep	`/v3/routing/suggest`

The request

The body has two required parts, problem and plan, plus optional options:

object

required

The same problem object as on /v3/routing/solve: jobs, shipments, vehicles, depots, relations, objective, travel. It must contain the tasks already in the plan and the tasks you want to place: every task not in plan is placed.

object

required

The committed plan, in the shape every solve and evaluate response returns as plan: one routes[] entry per vehicle shift, each with vehicle, shift and an ordered stops[] list. Leave the tasks to place out of it; at least one task of problem must be missing from it. A route’s locked_count marks stops that are already dispatched: no insertion lands before them.

integer

default:"5"

Maximum number of ranked insertions per task. 0 returns every feasible placement. Positive values above 100 are lowered to 100.

number

default:"1"

Search budget in seconds, at most 300; fractions are allowed (2.5). Defaults to 1, as on solve. A value below 0.1 is raised to 100 ms. The budget is split across the tasks to place in problem order, each getting an equal share of the time left. The clock starts when the search starts, so fetching travel times does not eat into it.

There is no list of task ids to send: a task you do not want suggestions for must either be in plan or be left out of problem. An old options.tasks field is rejected as unknown_field.

Example

One truck already serves delivery-1 and delivery-2. A third order, delivery-3, comes in and must be served between 08:00 and 11:00 local time.

curl -X POST https://api.solvice.io/v3/routing/suggest \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "problem": {
      "jobs": [
        {
          "id": "delivery-1",
          "location": [4.7005, 50.8798],
          "service_duration_s": 300,
          "time_windows": [
            { "from": "2026-04-01T09:00:00+02:00", "to": "2026-04-01T12:00:00+02:00" }
          ],
          "delivery": { "weight": 10 }
        },
        {
          "id": "delivery-2",
          "location": [3.7303, 51.0500],
          "service_duration_s": 600,
          "time_windows": [
            { "from": "2026-04-01T10:00:00+02:00", "to": "2026-04-01T15:00:00+02:00" }
          ],
          "delivery": { "weight": 20 }
        },
        {
          "id": "delivery-3",
          "location": [4.4776, 51.0259],
          "service_duration_s": 300,
          "time_windows": [
            { "from": "2026-04-01T08:00:00+02:00", "to": "2026-04-01T11:00:00+02:00" }
          ],
          "delivery": { "weight": 15 }
        }
      ],
      "vehicles": [
        {
          "id": "truck-1",
          "capacity": { "weight": 100 },
          "shifts": [
            {
              "id": "mon",
              "from": "2026-04-01T08:00:00+02:00",
              "to":   "2026-04-01T17:00:00+02:00",
              "start": { "location": [4.3517, 50.8503] },
              "end":   { "location": [4.3517, 50.8503] }
            }
          ]
        }
      ]
    },
    "plan": {
      "routes": [
        {
          "vehicle": "truck-1",
          "shift": "mon",
          "stops": [
            { "type": "job", "id": "delivery-1" },
            { "type": "job", "id": "delivery-2" }
          ]
        }
      ]
    },
    "options": {
      "max_suggestions": 3
    }
  }'

The response

{
  "suggestions": [
    {
      "job_id": "delivery-3",
      "insertions": [
        {
          "delta": { "cost": 4.4386, "distance_m": 22193, "duration_s": 1405 },
          "placements": [
            {
              "type": "job",
              "id": "delivery-3",
              "vehicle": "truck-1",
              "shift": "mon",
              "arrival": "2026-04-01T08:25:00+02:00",
              "latest_arrival": "2026-04-01T11:00:00+02:00"
            }
          ],
          "routes": [
            {
              "vehicle": "truck-1",
              "shift": "mon",
              "stops": [
                { "type": "job", "id": "delivery-3" },
                { "type": "job", "id": "delivery-1" },
                { "type": "job", "id": "delivery-2" }
              ]
            }
          ]
        },
        {
          "delta": { "cost": 7.3023, "distance_m": 5213, "duration_s": 344 },
          "placements": [
            {
              "type": "job",
              "id": "delivery-3",
              "vehicle": "truck-1",
              "shift": "mon",
              "arrival": "2026-04-01T09:31:30+02:00",
              "latest_arrival": "2026-04-01T11:00:00+02:00"
            }
          ],
          "routes": [
            {
              "vehicle": "truck-1",
              "shift": "mon",
              "stops": [
                { "type": "job", "id": "delivery-1" },
                { "type": "job", "id": "delivery-3" },
                { "type": "job", "id": "delivery-2" }
              ]
            }
          ]
        }
      ]
    }
  ],
  "truncated": false,
  "elapsed_ms": 184
}

The figures are illustrative; yours depend on live travel times. Three positions exist on this route and only two come back: inserting delivery-3 after delivery-2 would reach it after its window closes, so that position is not feasible and is not listed. suggestions[] has one entry per task outside plan, in the order the tasks appear in problem (jobs first, then shipments). Tasks tied together by a relation share one entry: see Shipments and related tasks.

string

The task this entry is about.

array

Feasible insertions, lowest delta.cost first. Empty when none was found; reason_code then says why.

string

Present only when insertions is empty: time_limit, candidates_exhausted or infeasible. See When a task gets no insertions. New codes may be added; handle a code you do not know generically.

string

Present exactly when reason_code is: the same fact as an English sentence, for people and logs.

boolean

One flag for the whole response. true when options.time_limit_s cut the search short for any task, or when an empty list for a multi-task unit is inconclusive. The lists may then be incomplete or miss the best insertion.

integer

Wall-clock time of the whole request, in milliseconds.

When a task gets no insertions

An empty insertions list is a 200, not an error. The entry’s reason_code says why, and reason says the same in a sentence:

`reason_code`	`reason`	What happened	What to do
`time_limit`	`Search truncated before a feasible insertion was found`	`options.time_limit_s` ran out before any position was found. `truncated` is `true`	Raise `options.time_limit_s`
`candidates_exhausted`	No feasible insertion found within the beam; raise `max_suggestions` to search wider	For a unit of several stops, the search kept only the most promising partial placements and none of them could be completed. This does not prove that no placement exists. `truncated` is `true`	Raise `options.max_suggestions`, or send `0` to search exhaustively
`infeasible`	`No feasible insertion position found`	The search finished. No position in the committed plan satisfies the hard constraints	Relax the task or add capacity, or send the plan to `/v3/routing/solve` as a warm start so the other stops can move

In code, branch on reason_code, never on reason. Only infeasible is final; the other two can change with a larger budget or search. New codes may be added: treat one you do not know as not final and show reason. truncated covers the whole response: a task whose list is not empty can also have been cut short, and carries no reason_code. Send one task per request when you need to know which task was cut short.

Reading an insertion

An insertion says what it changes (delta), which stops it adds (placements) and how every changed route reads with it in (routes).

Field	Meaning
`delta.cost`	The change in the plan’s `cost`, in your currency: what two `/evaluate` calls with and without the insertion would differ by, up to rounding. Negative when serving a task saves more `drop_fee` than it costs to route
`delta.distance_m`	The change in the routes’ summed `distance_m`, in metres
`delta.duration_s`	The change in the routes’ summed `time.travel_s`, in seconds. Driving time only: service and waiting are not counted
`placements`	One entry per stop the insertion adds, in route order
`routes`	Every `plan.routes[]` entry the insertion changes, whole, as it reads with the insertion in. A route you sent keeps its `locked_count` and its reload stops; a vehicle the plan did not use gets a new route
`interchangeable_vehicles`	Other unused vehicles, as `{ "vehicle", "shift" }` pairs, that give the same `delta` once swapped for `vehicle` and `shift` in `placements` and `routes`. Present only when the insertion opens a vehicle with no stops in `plan`

Insertions are ordered by delta.cost, lowest first. Each placement says who serves the new stop and when, which is what a booking screen shows:

Field	Meaning
`type`	The plan stop’s `type`: `job`, `pickup` or `delivery`
`id`	The plan stop’s `id`: the job id, or the shipment leg’s stop id
`vehicle`	Vehicle of the `plan.routes[]` entry the stop goes into
`shift`	Shift id of that route
`arrival`	When the vehicle would arrive at the new stop, in the UTC offset of the shift’s `from` (`Z` for a UTC `from`)
`latest_arrival`	The latest arrival at the new stop that keeps the rest of the route feasible, in the same offset as `arrival`

delta.cost and delta.duration_s measure different things. In the example the first insertion adds more driving than the second, yet costs less: the truck used to wait at delivery-1 for the window to open, and the detour fits inside that wait, so the route does not end any later. See Objective function for what the cost is made of.

Applying a suggestion

Suggest only reports insertions. To act on one, swap its routes into your plan:

Swap in the routes

For each entry of the insertion’s routes, replace the plan.routes[] entry with the same vehicle and shift, or add it when plan has none. To use one of interchangeable_vehicles instead, first put its vehicle and shift in the insertion’s route. For the first insertion above, plan becomes:

{
  "routes": [
    {
      "vehicle": "truck-1",
      "shift": "mon",
      "stops": [
        { "type": "job", "id": "delivery-3" },
        { "type": "job", "id": "delivery-1" },
        { "type": "job", "id": "delivery-2" }
      ]
    }
  ]
}

Confirm or re-optimise

Send the edited plan to /v3/routing/evaluate to get the full timeline and cost of the new plan, or to /v3/routing/solve as a warm start if the solver may also rearrange the other stops.

Each task is ranked on its own against the same committed plan. If two tasks are outside the plan and you apply an insertion for the first, the insertions for the second were computed without it: call suggest again with the updated plan.

Shipments. Leave both legs of the shipment out of plan. Its pickup and delivery are placed together, on one route: the insertion’s placements[] lists both legs in route order, each with its type of pickup or delivery and its leg’s stop id. A shipment with only one leg in plan is rejected by the plan import, as on evaluate.
sequence, same_vehicle and same_day relations. Tasks tied together by one of these relations are placed as one unit and get one entry, named after the first new task of the unit.
synchronized and time_lag relations. A task outside plan that takes part in one of these cannot be suggested, and one such task makes the whole request a 400, not just its own entry. Put the task in plan, or leave the relation out, to get suggestions for the other tasks.
Reloads. An insertion can land in any existing trip of a multi-trip route, but suggest never adds a new reload trip.

Errors

Suggest returns the same error body as the other endpoints. The cases specific to it:

Situation	Result
`plan` contains every task of `problem`	`400`, item `invalid_value`, pointer `/plan`
`options.tasks` is sent	`400`, item `unknown_field`
`options.time_limit_s` above `300`	`400`, item `limit_exceeded`, pointer `/options/time_limit_s`
Any task outside `plan` is in a `synchronized` or `time_lag` relation	`400` for the whole request
The plan does not fit the problem (unknown vehicle, shift or stop id, a stop listed twice, a shipment with one leg in `plan`)	`400`, pointer `/plan/routes/{i}` or `/plan/routes/{i}/stops/{k}`
No feasible position for a task	`200`, with an empty `insertions` list and a `reason_code`

?validate_only=true checks problem, options, and that plan leaves at least one task out, without fetching travel times or searching. It does not check that plan fits the problem; only the real call does.

Evaluate

Score the plan after you apply an insertion.

Errors

The error body, every code, and what to do about each.

The V3 API model

The problem and plan objects in full.

API reference

Request and response schema for every endpoint.

Platform

Routing API

Overview

The request

Example

The response

When a task gets no insertions

Reading an insertion

Applying a suggestion

Errors

Evaluate

Errors

The V3 API model

API reference

​Overview

​The request

​Example

​The response

​When a task gets no insertions

​Reading an insertion

​Applying a suggestion

​Shipments and related tasks

​Errors

Evaluate

Errors

The V3 API model

API reference

Overview

The request

Example

The response

When a task gets no insertions

Reading an insertion

Applying a suggestion

Shipments and related tasks

Errors