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 in each suggestions[] entry: an integer from 1 to 10. It caps the insertions per entry, not the number of entries. 0 is rejected with 400 (out_of_range) and a value above 10 with 400 (limit_exceeded); neither is clamped. It also sets how widely a task with several stops is searched: each stop after the first keeps at most max(8, 4 × max_insertions) partial placements. A crew is searched the same way whatever its value: every start slot of each member, with every slot of the other member when two members are outside plan, and a few slots of each other member when more are.

number

default:"1"

Search budget in seconds, at most 60; fractions are allowed (2.5). Defaults to 1. 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.

string

default:"estimate"

What to do when travel times cannot be fetched, as on /v3/routing/solve. estimate ranks the insertions on travel estimated from straight-line distance and a typical speed for the vehicle profile, and sets travel_estimated to true. fail returns the 502 or 503 instead. Coordinates that span more than one region are a 400 either way.

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. There is no options.tasks field: sending one is 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_load": { "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_load": { "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_load": { "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_insertions": 3
    }
  }'

The response

{
  "suggestions": [
    {
      "task": "delivery-3",
      "insertions": [
        {
          "delta": { "cost": 4.4386, "distance_m": 22193, "travel_s": 1405 },
          "placements": [
            {
              "type": "job",
              "id": "delivery-3",
              "vehicle": "truck-1",
              "shift": "mon",
              "arrival": "2026-04-01T08:25:00+02:00",
              "service_start": "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, "travel_s": 344 },
          "placements": [
            {
              "type": "job",
              "id": "delivery-3",
              "vehicle": "truck-1",
              "shift": "mon",
              "arrival": "2026-04-01T09:31:30+02:00",
              "service_start": "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,
  "timings": { "total_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 then says why.

object

Present only when insertions is empty. code is time_limit, candidates_exhausted or infeasible (new codes may be added; handle one you do not know as not final), and message says the same as an English sentence, for people and logs. See When a task gets no insertions.

boolean

One flag for the whole response. true when options.time_limit_s cut the search short for any task, when an empty list for a multi-task unit is inconclusive, or when a crew with three or more members outside plan lists fewer than max_insertions after it was refused where it had left slots untried. The lists may then be incomplete or miss the best insertion.

boolean

true when travel times could not be fetched and the insertions were ranked on estimated travel, as summary.travel_estimated on a solve. Every delta, arrival and feasibility verdict then holds only against the estimate, which can be tens of percent off. Absent when travel came from the road network. Send options.travel_fallback: "fail" to get an error instead.

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 says why: code to branch on, message in a sentence:

`reason.code`	`reason.message`	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_insertions` (up to 10) to search wider, or for a crew No placement of the whole group found; a crew with three or more members outside `plan` tries only a few slots per member, so `/v3/routing/solve` may still place it	For a unit of several stops, the search kept only the most promising partial placements and none of them could be completed. For a crew with three or more members outside `plan`, the few slots tried per member found no placement of the whole crew, and other slots were not tried. With one or two members outside `plan` every slot is tried (unless a member shares its location with a job that has a setup), so the code is `infeasible` instead, or `time_limit` if the deadline cut the search. This does not prove that no placement exists. `truncated` is `true`	Raise `options.max_insertions` (up to `10`): each stop after the unit’s first keeps `max(8, 4 × max_insertions)` partial placements. A larger `time_limit_s` does not search wider, and the code can persist. For a crew neither option helps: send the plan to `/v3/routing/solve`
`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.message. 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.message. truncated covers the whole response: a task whose list is not empty can also have been cut short, and carries no reason. 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_cost` than it costs to route
`delta.distance_m`	The change in the routes’ summed `distance_m`, in metres
`delta.travel_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`, its reload stops and every stop’s `pinned` flag; 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`. Every vehicle listed is correct, but the list can miss some

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`)
`service_start`	When service would start, in the same offset: `arrival` plus any wait for the time window or a break, and for a crew member the wait for the rest of the crew. With the default `on: service_start`, a crew’s booking time
`latest_arrival`	The latest arrival at the new stop that keeps the rest of the route feasible, in the same offset as `arrival`. With priced lateness it can be earlier than `arrival`. For a crew member it is at most `arrival` plus the wait before `service_start`, so the crew’s start does not move

delta.cost and delta.travel_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, same_day and same_route 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. Only the tasks outside plan form the unit; a member already in plan constrains where the others can go.
synchronized and time_lag relations. The tasks one of these ties together are placed as one unit: see Crews.
Reloads. An insertion can land in any existing trip of a multi-trip route, but suggest never adds a new reload trip.

Crews: `synchronized` and `time_lag`

A job that needs several technicians is one job per technician in a synchronized relation (see Constraints). Leave every member out of plan and suggest finds the times when the whole crew is available:

The crew gets one suggestions[] entry, named after the member that comes first in jobs. Each insertion places every member: placements[] has one entry per member and routes[] every route they go into, so applying it books the whole crew.
With the default on: service_start, the members start within max_spread_s of one another (with on: departure they finish within it), so with a spread shorter than the service each is on a different vehicle. Read the booking time from service_start: a member who arrives earlier waits for the others, shown as hold_s on the stop when you /evaluate the applied plan.
One delta.cost covers the whole crew, and insertions are ranked by it across every route and shift in plan, so a cheaper day comes first.
Two insertions that differ only in which member goes to which of the same vehicles, at the same times and cost, are listed once when the swapped members share a location and service time.
A member already in plan keeps its route and position, and the others are placed to meet it. It may be held later to meet them, which delays the stops after it on its route: /v3/routing/evaluate of the applied plan shows the wait as hold_s, and delta.cost includes it. routes[] lists only the routes whose stops change, so that route is not in it.
Tasks a time_lag ties together are placed the same way, with the lag kept.

Every start slot of each member is tried, whichever members eligible_vehicles restricts. With two members outside plan, every slot of the other member is tried against each start, so the cheapest pairing is listed even when the other member’s cheapest slot would make the crew wait. With more, each other member, those fewer vehicles can serve first, is placed at its two cheapest slots and at the slot arriving nearest the first member’s start, so a different combination can cost slightly less than the one listed. A plan whose committed crews already break their own synchronized or time_lag relation still gets insertions for a new crew: each one keeps that violation and adds none, as /v3/routing/evaluate of the applied plan shows. One case is not supported: a crew member that a sequence, consecutive, same_vehicle, same_day, same_route or all_or_none relation also ties to a task outside the crew, such as an all_or_none over two crews. It makes the whole request a 400, item not_supported, pointing at the member. Put the other task, or the crew, in plan.

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 `60`	`400`, item `limit_exceeded`, pointer `/options/time_limit_s`
`options.time_limit_s` negative	`400`, item `out_of_range`, pointer `/options/time_limit_s`
A crew member outside `plan` is also tied, by a `sequence`, `consecutive`, `same_vehicle`, `same_day`, `same_route` or `all_or_none` relation, to a task outside its crew	`400` for the whole request, item `not_supported`, pointer `/problem/jobs/{i}`; the message names the task
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}`
Travel times cannot be fetched	`200`, ranked on estimated travel times, with `travel_estimated: true`; the insertions and their `delta` hold only against the estimate. With `options.travel_fallback: "fail"`, `502` `travel_provider_error`, or `503` with `Retry-After` while the travel-time service is temporarily cut off. Coordinates that span more than one region are a `400`
No feasible position for a task	`200`, with an empty `insertions` list and a `reason`

POST /v3/routing/validate/suggest 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

Crews: `synchronized` and `time_lag`

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

Crews: synchronized and time_lag

Errors

Evaluate

Errors

The V3 API model

API reference

Crews: `synchronized` and `time_lag`