Migration from V2 - Solvice Docs

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

Overview

V2 (OnRoute) and V3 describe the same routing problem in different vocabularies. This page maps one to the other: endpoints, request fields, relations, the objective, and the response. The tables below show, for each V2 field, the V3 field that replaces it and how the meaning differs. Some V2 fields have no direct V3 equivalent: V2 fields with no direct V3 equivalent lists them and what to send in V3 instead.

Three conventions cover most of the work: names become snake_case with a unit suffix (_s seconds, _m metres), positional arrays become named maps, and V2 weights are replaced by prices in the objective’s currency that you set yourself. See From weights to prices.

How to port a request

List what has no direct equivalent

Check every field your V2 request sends against V2 fields with no direct V3 equivalent. A field in that list has no one-to-one V3 field, so decide its V3 replacement before you start.

Rewrite the body

Wrap the problem in problem, then rename fields with the Conventions, Vehicles, Shifts and Jobs tables. Give every shift an id.

Convert relations and pickup-delivery pairs

Rewrite relations[] with the Relations table, and turn each PICKUP_AND_DELIVERY pair into a shipments[] entry.

Set the objective explicitly

A V3 request without objective prices time and distance at default rates. Read Default objective, then convert the weights you rely on with From weights to prices.

Move the warm start and the options

Replace initialResource and initialArrival with a request-level plan (see Existing plans), and move the time budget and the other options with the Options table.

Validate without solving

Send the request to POST /v3/routing/validate/solve. A valid request returns {"valid": true, "warnings": []}. An invalid one returns the 400 the real call would return: fix each errors[] item at its pointer. A leftover V2 key shows up as unknown_field. See Errors.

Solve and compare

Solve the same instance and read the result with the Response mapping tables. Compare unassigned[], the route totals and the stop order with your V2 result before you switch traffic.

Endpoints and lifecycle

V2	V3	Notes
`POST /v2/vrp/sync/solve`	`POST /v3/routing/solve`	Request in, plan out, in one call
`POST /v2/vrp/sync/evaluate`	`POST /v3/routing/evaluate`	Scores a plan you supply without optimizing it. See Evaluate
`POST /v2/vrp/sync/suggest`	`POST /v3/routing/suggest`	Ranks insertion positions for new tasks in an existing plan. See Suggest
`POST /v2/vrp/solve` (submit a job)	`POST /v3/routing/runs`	Answers `202` with a run and solves in the background. The body is the solve body. See Async runs
`GET /v2/vrp/jobs/{id}`, `/status`	`GET /v3/routing/runs/{id}`	The run’s `status` is `queued`, `running`, `succeeded`, `failed` or `cancelled`
`GET /v2/vrp/jobs/{id}/solution`	`GET /v3/routing/runs/{id}/result`	The same response `/v3/routing/solve` returns
`POST /v2/vrp/evaluate`, `POST /v2/vrp/suggest` (submit a job)	No counterpart in this reference	Evaluate and suggest are request/response: the result is the response body
`GET /v2/vrp/jobs/{id}/explanation`, `/debug`	No counterpart in this reference	See below
`POST /v2/vrp/jobs/{id}/change`	No counterpart in this reference	Edit the `plan` and send it again, see below
`hook` callback	No counterpart in this reference	A run takes no `callback` yet (a `400`): poll it

Only solve has a background form. The three synchronous V3 endpoints hold the connection open until the result is ready: a solve searches for options.time_limit_s seconds (at most 60), and fetching travel times comes on top of that. Set your HTTP client timeout above the budget you send, or submit a run, which searches for up to 3600 seconds without holding a connection. See Limits. What each V2 step gave you is available like this:

Solution. The body of the solve response, or /result of a run.
Explanation. Every entry of unassigned[] carries a category, machine-readable reasons[] and best-effort relaxations[]. For a plan you built or edited yourself, evaluate reports violations[] per stop and per route.
Change. Keep the plan from the response, edit it, and send it back: to evaluate to score the edit, or to solve as a warm start. locked_count on a plan route freezes its first stops.

Existing plans

Solve (as a warm start), evaluate and suggest all take an existing plan, and its shape changes. V2 reads it from jobs[].initialResource and jobs[].initialArrival; V3 takes an explicit plan object next to problem, which is exactly what a V3 response returns under plan. Each plan.routes[] entry names its vehicle and its shift, and lists its stops in order. On suggest, V2 places the jobs that have no initialResource; V3 places every task of problem that is not in plan.

{
  "jobs": [
    { "name": "delivery-1", "initialResource": "truck-1", "initialArrival": "2026-04-01T09:00:00+02:00" },
    { "name": "delivery-2", "initialResource": "truck-1", "initialArrival": "2026-04-01T10:30:00+02:00" }
  ]
}

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

A native plan differs from the V2 job fields in these ways:

Shift per route. plan.routes[].shift names the shift each route runs on, so a plan can span several days. V2 has no per-job shift.
Order only. A plan lists stops in visiting order, and V3 recomputes every arrival time from that order. V2 initialArrival values are not sent.
Freezing. Set locked_count on a plan route to freeze its first stops.
Reloads. V2 initialDepot becomes a { "type": "reload", "depot": "<depot id>" } stop in the plan route.
Shipments. A shipment appears in the plan as pickup and delivery stops. See Pickup and delivery pairs.

To keep a re-solve close to the previous plan, send that plan back as plan.

Conventions

	V2 (OnRoute)	V3 (Routing)
Base URL	`https://api.solvice.io`	`https://api.solvice.io`
Auth	`Authorization: API_KEY`	`Authorization: API_KEY`
Body	Problem fields at the top level	`{ "problem": { ... }, "plan": { ... }, "options": { ... } }`
Field naming	camelCase	snake_case
Coordinates	`{ "latitude": 50.85, "longitude": 4.35 }`	`[4.35, 50.85]` (GeoJSON order: longitude, latitude)
Times	ISO 8601 strings	ISO 8601 strings. A UTC offset (`+02:00` or `Z`) is required: a time without one is a `400`, where V2 accepted it and read it as UTC. V2 also accepted a Java zone id after the offset (`2026-04-01T09:00:00+02:00[Europe/Brussels]`); V3 does not, so send the part before `[`. V2 response times are UTC. V3 response times are in the UTC offset of the shift’s `from` (`Z` for a UTC `from`): the same instant, written in that offset
Durations and distances	Seconds and metres, no suffix	Seconds and metres, with `_s` and `_m` suffixes
Identifiers	`name`	`id`; every shift also needs an `id`
Unknown fields	Tolerated	Rejected with HTTP `400` and `errors[].code: "unknown_field"`. See Errors
Capacity dimensions	Positional array, up to 5	Named map, up to 4 dimensions across the request. A fifth dimension is a `400`
Check a request without solving	Not available	`POST /v3/routing/validate/{solve,evaluate,suggest}`

Request mapping

Vehicles (resources)

{
  "name": "truck-1",
  "shifts": [
    {
      "from": "2026-04-01T08:00:00+02:00",
      "to": "2026-04-01T17:00:00+02:00",
      "start": { "latitude": 50.8503, "longitude": 4.3517 },
      "end": { "latitude": 50.8503, "longitude": 4.3517 }
    }
  ],
  "capacity": [100],
  "tags": ["refrigerated"]
}

{
  "id": "truck-1",
  "capacity": { "weight": 100 },
  "skills": [{ "name": "refrigerated" }],
  "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] }
    }
  ]
}

V2 `resources[]`	V3 `vehicles[]`	Notes
`name`	`id`	Unique across vehicles, 1 to 128 characters
`capacity` (array)	`capacity` (named map)	`[100]` becomes `{ "weight": 100 }`. You choose the names; they must match the keys of job `pickup_load`. At most 4 names across the request
`tags`	`skills`	One `{ "name": tag }` object per tag. A bare string is rejected
`category`	`profile`	`car` (default), `truck` or `bike`. No automatic equivalent: set `profile` yourself
`start`, `end` (resource level)	`shifts[].start`, `shifts[].end`	V3 has no vehicle-level fallback: put the location on each shift
`shifts[]`	`shifts[]`	One V3 shift per V2 shift. See the next table
`rules[]`	`quotas[]`, `limits.periods[]`	See Period rules
`maxDriveTimeJob`	`limits.max_leg_travel_s`	A cap on any single travel leg, the legs from `start` and to `end` included. A value of `0` or below capped nothing in V2 and is a `400` in V3: leave the field out
`compatibleResources` (with `enforceCompatibility` on a relation)	`compatible_with`	Used by a `compatible_vehicles` relation. Two vehicles serve the relation’s jobs together only if neither list excludes the other, as in V2. V3 rejects an empty list: where V2 sent `[]`, list the vehicle’s own id. Without a list a vehicle pairs with any vehicle
(no `shifts`)	`shifts[]` with one entry	V3 requires at least one shift: give the vehicle one shift with its `start` and `end`

Per-vehicle limits live under limits: limits.max_distance_m takes the place of V2 maxDriveDistance, and limits.max_route_duration_s caps the whole route span (travel, service and waiting), not driving time alone. V3 has no cap on a route’s total driving time, so maxDriveTimeInSeconds and maxDriveTime have no counterpart.

Shifts

V2 `shifts[]`	V3 `shifts[]`	Notes
(unnamed)	`id`	Required, unique within the vehicle, 1 to 128 characters. Echoed as `routes[].shift` and used in `plan`
`from`, `to`	`from`, `to`	Unchanged
`start`, `end`	`start`, `end`	Wrapped: `{ "location": [lon, lat] }`, or `{ "depot": "<depot id>" }` to reference `depots[]`. Omitted means an open start or end, with no leg to or from a depot
`overtimeEnd`	`max_overtime_s`	Seconds of overtime allowed: `overtimeEnd` minus `to`. Price it with `objective.costs.per_overtime_hour`
`overtime` (deprecated boolean)	`max_overtime_s`	No automatic equivalent: state the allowed overtime in seconds
`ignoreTravelTimeToFirstJob`	`free_start_travel`	The leg from `start` to the first task costs nothing. Send it only with `start`; V2 ignored it on an open start, V3 returns 400
`ignoreTravelTimeFromLastJob`	`free_end_travel`	The leg from the last task to `end` costs nothing. Send it only with `end`
`shiftStartsAtFirstJobLocation`	`start_at_first_task`	The leg from `start` takes no time but its distance is still charged. V2 also charged its travel time; V3 does not, so with an hourly cost V3 scores differ slightly. Send it only with `start` and without `free_start_travel` (V2’s `ignoreTravelTimeToFirstJob` won when both were set)
`tags`	`skills`	Replaces the vehicle’s `skills` for that shift
`breaks[]`	`breaks[]`	See below

Multi-day planning works the same way in both versions: one shift per working day. In V3 each shift has its own id, and each route reports the shift it runs on.

Breaks

[
  { "type": "WINDOWED", "from": "2026-04-01T12:00:00+02:00", "to": "2026-04-01T13:00:00+02:00", "duration": 1800 },
  { "type": "DRIVE", "driveTime": 16200, "duration": 2700 },
  { "type": "UNAVAILABILITY", "from": "2026-04-01T15:00:00+02:00", "to": "2026-04-01T15:30:00+02:00" }
]

[
  { "type": "windowed", "duration_s": 1800, "time_window": { "from": "2026-04-01T12:00:00+02:00", "to": "2026-04-01T13:00:00+02:00" } },
  { "type": "triggered", "duration_s": 2700, "after": "drive", "threshold_s": 16200 },
  { "type": "fixed", "from": "2026-04-01T15:00:00+02:00", "to": "2026-04-01T15:30:00+02:00" }
]

V2 break `type`	V3 break	Notes
`WINDOWED`	`windowed` with a single `time_window`	`duration` becomes `duration_s`. The window bounds the break’s start, and `to` is a hard latest start. A V3 `windowed` break has no `location` (`400`, `not_supported`): it is taken wherever the vehicle is
`DRIVE`	`triggered` with `after: "drive"`	`driveTime` becomes `threshold_s`
`DUTY`	`triggered` with `after: "duty"`	`workTime` becomes `threshold_s`
`UNAVAILABILITY`	`fixed`	`from` and `to` unchanged. A `location` is not supported

deductPreviousBreaks has no V3 counterpart: model each accumulation window as its own break.

Depots (multi-trip reloads)

{
  "depots": [
    { "name": "hub", "location": { "latitude": 51.0500, "longitude": 3.7250 }, "duration": 300 }
  ]
}

{
  "depots": [
    { "id": "hub", "location": [3.7250, 51.0500], "service_duration_s": 300 }
  ],
  "vehicles": [
    {
      "id": "truck-1",
      "shifts": [
        {
          "id": "mon",
          "from": "2026-04-01T08:00:00+02:00",
          "to": "2026-04-01T17:00:00+02:00",
          "reloads": ["hub"]
        }
      ]
    }
  ]
}

depots[] is top-level in both versions. In V2 every shift may use every depot; in V3 a shift opts in by naming depot ids in its own reloads[]. A shift without reloads is single-trip.
name becomes id, and duration becomes service_duration_s. Both keep one handling time per depot.
cost becomes per_reload, charged once per reload. No automatic equivalent: set per_reload yourself.
A depot can also be a shift’s start or end: "start": { "depot": "hub" }.
shifts[].max_trips caps the number of trips in a shift. V2 has no such cap.

Jobs

{
  "name": "delivery-1",
  "location": { "latitude": 50.8798, "longitude": 4.7005 },
  "duration": 300,
  "load": [10],
  "priority": 2,
  "tags": [{ "name": "refrigerated", "hard": true }],
  "windows": [
    {
      "from": "2026-04-01T09:00:00+02:00",
      "to": "2026-04-01T12:00:00+02:00",
      "hard": true
    }
  ]
}

{
  "id": "delivery-1",
  "location": [4.7005, 50.8798],
  "service_duration_s": 300,
  "pickup_load": { "weight": 10 },
  "priority": 2,
  "required_skills": [{ "name": "refrigerated" }],
  "time_windows": [
    {
      "from": "2026-04-01T09:00:00+02:00",
      "to": "2026-04-01T12:00:00+02:00"
    }
  ]
}

V2 `jobs[]`	V3 `jobs[]`	Notes
`name`	`id`	Unique across `jobs` and `shipments`, 1 to 128 characters
`location`	`location`	`[lon, lat]`. Omit it for a job with no location of its own: it is served wherever the vehicle already is
`duration`	`service_duration_s`	Seconds
`durationSquash`	`setup_duration_s` + `service_duration_s`	`setup_duration_s = duration - durationSquash` and `service_duration_s = durationSquash`. Setup is paid once on arrival at a location and skipped for the next stop at the same location
`load` (array)	`pickup_load` (named map)	`[10]` becomes `{ "weight": 10 }`
`windows[]`	`time_windows[]`	See Time windows
`tags[]` with `hard: true`	`required_skills[]`	See Tags
`priority`	`priority`	See Priority and optional jobs
`plannedArrival` + `urgency`	`target`	`{ "at": plannedArrival, "on": "arrival", "per_late_hour": <price> }`. Prices lateness only. See Planned arrival and urgency
`rankings[]`	`assignment_costs[]`	One `{ "vehicle", "cost" }` entry per vehicle: the price charged when that vehicle serves the job. A vehicle you do not list costs nothing, while V2 counts an unranked resource as ranking `100`, so list every vehicle and give the most preferred the smallest `cost`. See From weights to prices
`proficiency[]`	`service_factors[]`	`{ "vehicle": resource, "factor": 1 / durationModifier }`. V2 multiplies the duration, V3 divides it, so `0.8` becomes `1.25`. Maximum factor `5`
`plannedResource`	`eligible_vehicles.allowed: [plannedResource]`	Hard pin to one vehicle, on any of its shifts. Unlike a V2 pin, the search may still re-place the job on that vehicle; to freeze dispatched stops, use `plan.routes[].locked_count`. An id that matches no vehicle is a `400`
`allowedResources`	`eligible_vehicles.allowed`	Hard whitelist. V2 ignored ids that name no resource in the request; in V3 an id that matches no vehicle is a `400`
`disallowedResources`	`eligible_vehicles.excluded`	Hard blacklist. `allowed` and `excluded` cannot be combined on one job
`initialResource` + `initialArrival`	request-level `plan`	The warm start is a `plan` object next to `problem`, not a job field. See Existing plans
`jobTypes`	`quotas[].tasks`	No job field. See Period rules
`resumable`	`break_interruptible`	A `fixed` break inside the service pauses the job, as an `UNAVAILABILITY` break does in V2. In V3 a `windowed` break or a duty-`triggered` break can pause it too; V2 takes those between jobs. The job stop reports the paused seconds in `break_s`

Time windows

A V3 window has no hard flag and no weight. It is hard unless lateness is priced:

Per window: time_windows[].per_late_hour makes that window soft on its late side, at that price per hour. It is allowed only on a task with exactly one window and must be greater than 0. This is where a V2 hard: false window goes.
Fleet-wide: objective.per_late_hour prices lateness on every window that does not set its own rate.

Arriving early always waits for from. A job with several windows cannot make them soft: per_late_hour is allowed only on a task with exactly one window. To keep a V2 soft window beside hard windows, keep the hard windows and add a target whose at is the soft window’s to. Only lateness past that end is priced. Raise a window’s from to the soft start only if service before it must be forbidden; that changes which plans are feasible. A job can list several windows and is served in one of them. An optional time_windows[].choice_cost ranks them when one window is preferred over another; it cannot be combined with objective.per_late_hour.

Priority and optional jobs

V3 has two separate mechanisms. Pick by what should happen when not every job fits.

	`priority`	`drop_cost`
What it is	A rank, an integer of at least `1`, default `1`	A price in the objective’s currency
Effect	The job stays must-serve. When not every must-serve job fits, the solver maximises the summed `priority` of the jobs it serves before it looks at cost	The job becomes optional. It is served only while serving it costs less than the fee
Reported as	`summary.score.unassigned_priority`	`summary.score.components.drop_costs`
Use it when	Every job should be served if at all possible, and some matter more than others	A job is worth serving only up to a certain cost

V2 priority maps to V3 priority. The V2 reference weighs an unserved job by priority × duration. To keep V2’s ranking, send that product (duration in seconds) as the V3 priority, or send your own rank if job length should not count. priority and drop_cost cannot be combined on one job (400). A job with neither field is must-serve.

Planned arrival and urgency

A V3 target is a point in time with a price for missing it on the late side:

V3 target

{
  "id": "delivery-1",
  "location": [4.7005, 50.8798],
  "target": {
    "at": "2026-04-01T10:00:00+02:00",
    "on": "arrival",
    "per_late_hour": 60
  }
}

per_late_hour is required and must be greater than 0. It is charged per hour of arrival after at, prorated per second.
Arriving before at costs nothing, and the vehicle does not wait for at. V2 documents plannedArrival as “as close as possible” to the planned time; a V3 target does not price the early side. Add a time_windows entry when the job must not start before a given time.
"on": "departure" measures the end of service instead of the arrival.

A target needs a price you choose. Port the V2 inputs like this:

V2 job sends	V3
`plannedArrival` and `urgency` > `0`	`target` at `plannedArrival`, with `"on": "arrival"` and a `per_late_hour` you choose
`plannedArrival` without `urgency`, or with `urgency: 0`	`target` with a `per_late_hour` you choose; without one the job has no target
`urgency` without `plannedArrival`	No equivalent: V3 has no “schedule earlier in the day” preference
`weights.plannedWeight`, `weights.urgencyWeight`	No equivalent: V3 has no weights. See From weights to prices

Relations

V3 relations are a tagged union under problem.relations[], with members in stops instead of jobs. All V3 relations are hard: there is no relation weight. Every V2 relation type is listed here.

V2 `type`	V3	Notes
`SEQUENCE`	`sequence`	`stops` in order: members that share a route appear on it in that order, and other stops may sit in between. It does not put the members on one vehicle; add `same_vehicle` for that. A single job id pins that job as the first stop of its route. V2 also kept that order across resources: with more than one vehicle, add a `time_lag` with `min_s: 0` per consecutive pair next to the `sequence`. Tasks linked across vehicles this way count toward the limit of 16 per linked group (see Limits)
`SEQUENCE` with `minTimeInterval` or `maxTimeInterval`	`time_lag`	One relation per consecutive pair: `from` and `to` ends with `min_s` and `max_s`. `timeInterval: FROM_DEPARTURE` becomes `"on": "departure"` on `from`. The two jobs may be on different vehicles. Jobs only, not shipments
`DIRECT_SEQUENCE`	`consecutive` + `same_vehicle`	Same vehicle, same order, no other stop in between. A list with a forked or joined stop (`[a, b]` and `[a, c]`) stays a `sequence`. `minTimeInterval` and `maxTimeInterval` need a `time_lag` per consecutive pair, see below
`SAME_RESOURCE`	`same_vehicle`	`stops`, or a `tag` that selects the members
`SAME_DAY`	`same_day`	`stops`, or a `tag`
`SAME_TRIP`	`same_route` (+ `all_or_none`)	One shift of one vehicle, as in V2; reloads within the shift do not split it. `stops`, or a `tag`. The `same_route` covers jobs only, not shipments. For a `SAME_TRIP` with `partialPlanning: false` over a pickup-and-delivery pair and a `DIRECT_SEQUENCE` chain of the same jobs (a tow between the pickup and the delivery), add an `all_or_none` over the shipment id and the other jobs of the chain, so the whole chain is served or none of it. See `partialPlanning`
`SAME_TIME`	`synchronized` + `all_or_none`	`stops` plus a required `max_spread_s` (`0` means simultaneous): set it to the time tolerance you want. Add an `all_or_none` over the same `stops` unless the V2 relation sets `partialPlanning: true`. `timeInterval: FROM_DEPARTURE` becomes `"on": "departure"`. With a nonzero `minTimeInterval` between two jobs, use a `time_lag` instead
`SAME_TIME` with `enforceCompatibility: true`	`compatible_vehicles`	Next to the `synchronized` relation, over the same `stops`. The vehicles that may serve the jobs together come from `vehicles[].compatible_with`, the V3 form of `compatibleResources`
`PICKUP_AND_DELIVERY`	a `shipments[]` entry	Not a relation: a shipment has a `pickup` and a `delivery` stop served by one vehicle in that order. See Pickup and delivery pairs
`GROUP_SEQUENCE`	`tag_order`	`tags` lists tag labels in order, and each job carries its label in `jobs[].tags`. At least two groups, jobs only, one such relation per request
`NEIGHBOR`	No equivalent

{
  "type": "SEQUENCE",
  "jobs": ["job-A", "job-B", "job-C"],
  "resource": "truck-1"
}

{
  "type": "sequence",
  "stops": ["job-A", "job-B", "job-C"]
}

A V2 relation’s resource pins every member to that vehicle. V3 relations have no such field: set eligible_vehicles: { "allowed": [resource] } on each job instead. Relation fields that change meaning:

SAME_TIME tolerance. The V2 reference documents maxWaitingTime (default 1200 seconds). V3 max_spread_s is required: set it explicitly.
SAME_TIME with minTimeInterval on three or more jobs: write one time_lag per pair.
DIRECT_SEQUENCE time intervals. V2 applies minTimeInterval and maxTimeInterval to DIRECT_SEQUENCE as well as to SEQUENCE. In V3, add one time_lag per consecutive pair next to the sequence and same_vehicle relations:
V3 relations for a DIRECT_SEQUENCE with a time interval
[ { "type": "sequence", "stops": ["job-A", "job-B"] }, { "type": "same_vehicle", "stops": ["job-A", "job-B"] }, { "type": "time_lag", "from": { "stop": "job-A" }, "to": { "stop": "job-B" }, "min_s": 600, "max_s": 3600 } ]
The lag is measured between the two service starts. Add "on": "departure" to from for V2 timeInterval: FROM_DEPARTURE.
hardMinWait and weight have no V3 counterpart: a time bound cannot be softened and a relation cannot be weighted.
Overlapping relations. V2 lets a job sit in several relations of one type. In V3 a job may be named by at most one same_vehicle, one same_day, one same_route and one synchronized relation; a second one is a 400. Merge overlapping same_vehicle or same_route members into one relation. For a job in several SAME_TIME relations, write one time_lag per pair of members instead, with min_s set to minus the tolerance and max_s to the tolerance.
partialPlanning. same_vehicle, same_day and time_lag bind the members that are served: a member that ends up in unassigned[] imposes nothing on the others, and sequence only orders the members that share a route. That is the V2 partialPlanning: true behaviour. V2 defaults to partialPlanning: false, so a SAME_TIME relation of two or more jobs that does not set it to true is all-or-nothing. To keep that in V3, add an all_or_none relation over the same stops next to the synchronized one. A SAME_TRIP is all-or-nothing in V2 unless it sets partialPlanning: true. V3 has an all-or-nothing form for one shape of it: a pickup-and-delivery pair and a DIRECT_SEQUENCE through the same jobs, with a job such as a tow between the pickup and the delivery. To keep it, add an all_or_none over the shipment id and the other jobs of the consecutive chain, and name the whole chain. Otherwise all_or_none takes jobs that a synchronized or time_lag relation also names, or jobs that form one consecutive chain, so for the other relation types check unassigned[] for members of the relation after each solve. A shipment is different: it is one task, so its pickup and delivery are served as a pair or the shipment is listed once in unassigned[].

Pickup and delivery pairs

A V2 pickup-and-delivery pair is two jobs plus a relation. In V3 it is one shipments[] entry and no relation.

{
  "jobs": [
    {
      "name": "pickup-1",
      "location": { "latitude": 51.0500, "longitude": 3.7250 },
      "duration": 300,
      "load": [20],
      "windows": [
        { "from": "2026-04-01T08:00:00+02:00", "to": "2026-04-01T10:00:00+02:00" }
      ]
    },
    {
      "name": "dropoff-1",
      "location": { "latitude": 51.0600, "longitude": 3.7100 },
      "duration": 600,
      "windows": [
        { "from": "2026-04-01T09:00:00+02:00", "to": "2026-04-01T12:00:00+02:00" }
      ]
    }
  ],
  "relations": [
    { "type": "PICKUP_AND_DELIVERY", "jobs": ["pickup-1", "dropoff-1"] }
  ]
}

{
  "shipments": [
    {
      "id": "order-1",
      "pickup": {
        "id": "pickup-1",
        "location": [3.7250, 51.0500],
        "service_duration_s": 300,
        "time_windows": [
          { "from": "2026-04-01T08:00:00+02:00", "to": "2026-04-01T10:00:00+02:00" }
        ]
      },
      "delivery": {
        "id": "dropoff-1",
        "location": [3.7100, 51.0600],
        "service_duration_s": 600,
        "time_windows": [
          { "from": "2026-04-01T09:00:00+02:00", "to": "2026-04-01T12:00:00+02:00" }
        ]
      },
      "load": { "weight": 20 }
    }
  ]
}

Where each V2 job field goes:

On the leg (pickup or delivery): location, setup_duration_s, service_duration_s and time_windows. A leg id is optional; set it to the V2 job name to keep that name on the stop in the response.
Once on the shipment: load (the load carried from pickup to delivery), priority, drop_cost, required_skills, eligible_vehicles, preferences, service_factors, assignment_costs and target. They apply to the pair.
The shipment id must be unique across jobs and shipments.

V2 sets these fields on each of the two jobs and a shipment has them once, so where the two V2 jobs differ, choose the value the pair gets. A V2 relation’s resource becomes eligible_vehicles.allowed with that one id, as does a plannedResource on either job. To keep a pair as two jobs instead, use a sequence and a same_vehicle relation over them.

Period rules

V2 resources[].rules[] splits across two V3 mechanisms.

V2 rule field	V3	Notes
`jobTypeLimitations` with `jobs[].jobTypes`	`quotas[]`	One quota per job type: `{ "id", "vehicles", "tasks", "max_stops" }`, where `tasks` lists the jobs of that type
`period`	`quotas[].from` and `to`	A stop counts toward the quota when its service starts in the window, so a window may sit inside one shift. Without a window every stop counts
`groupTag`	`quotas[].vehicles`	List every vehicle that shares the cap
`maxWorkTime`	`limits.periods[].max_route_duration_s`	Closest match. V3 caps the summed route span, which includes waiting
`maxServiceTime`, `maxDriveTime` (on a rule)	No equivalent	V3 has no service-only or drive-only cap
`minWorkTime`, `minServiceTime`, `minDriveTime`	No equivalent	V3 has no minimums
`minJobComplexity`, `maxJobComplexity`	No equivalent

limits.periods[] caps a vehicle’s totals per "every": "day", per "every": "week", or per explicit from and to window, with any of max_route_duration_s, max_distance_m and max_stops. A shipment counts as two stops toward max_stops. See Constraints.

Options

POST /v2/vrp/sync/solve?millis=5000

{
  "options": {
    "time_limit_s": 5,
    "seed": 42
  }
}

V2	V3	Notes
`?millis=` (milliseconds)	`options.time_limit_s`	Seconds, fractions allowed: `?millis=2500` is `2.5`. Default 150 ms plus 4 ms per task (per job on V2), maximum `60`. A larger value is a `400`. A value below `0.1` asks for the minimum search time of 100 ms. Suggest takes the same field: a V2 suggest without `?millis=` searches without a deadline, a V3 suggest for 1 second by default
`options.minimizeResources`	`objective.costs.per_route`	See Default objective
`options.jobProximityRadius`	`objective.grouping.radius_m`	`objective.grouping` also requires `per_entry`, a currency amount between `0` and `1000`
`options.jobProximityDistanceType`	`objective.grouping.distance_metric`	`HAVERSINE` becomes `straight_line` (the default), `REAL` becomes `road`
`options.maxSuggestions`	`options.max_insertions` on suggest, the cap on insertions per task	The default differs. The V2 reference documents `0` (every placement) as the default. V3 returns `5` insertions per task when the field is omitted and accepts `1` to `10`; `0` and values above `10` are a `400`, never clamped, so there is no way to ask for every placement
`options.routingEngine`	`problem.travel.engine`	`TOMTOM` becomes `tomtom`, `OSM` becomes `osm` and `TOMTOM_REAL_TIME` becomes `tomtom_real_time`, which is not enabled yet (a request that sets it is rejected with `403`). `euclidian` is `straight_line`, see Option fields. `GOOGLE` and `ANYMAP` have no V3 value. Without an engine V3 uses `osm`, or `tomtom` when `departure_time` is set; set `engine: "tomtom"` to price traffic at the moment of the request. No automatic equivalent: set `travel.engine` yourself
`options.polylines`	`options.polyline`	`"simplified"` or `"full"` instead of a boolean. Geometry is returned as `routes[].polyline`
`options.partialPlanning`	Always on	A job that cannot be served is returned in `unassigned[]`
(none)	`options.travel_fallback`	When travel times cannot be fetched, a V3 solve defaults to `estimate`: it solves on estimated travel and sets `summary.travel_estimated`. Send `"fail"` to get a `502` or `503` instead.

New in V3: options.seed for repeatable runs, and problem.travel.departure_time to plan against the traffic of a given instant (not with osm). V3 has no caller-supplied distance matrix. The API computes travel times and distances itself, selected by travel.engine and vehicles[].profile.

Default objective

A V3 request that sends no objective is optimized with the V3 defaults, which price distance as well as time. Amounts are in the objective’s currency.

	Native V3 request without `objective`
Time	35 per hour of route span (travel, service, waiting and breaks)
Distance	0.20 per kilometre
Vehicles used	Free, unless you set `per_route` or `per_used_vehicle` on `objective.costs` or a vehicle’s `costs`
Waiting, overtime, lateness	Not priced separately until you set `per_wait_hour`, `per_overtime_hour` or `per_late_hour`

A request ported field for field therefore starts paying for distance, which can change which routes win. To optimize route time only, set the distance rate to zero. Rates you leave out keep their defaults:

{
  "objective": {
    "costs": { "per_travel_km": 0 }
  }
}

V2 options.minimizeResources: true becomes a per_route charge, paid once per route, so a vehicle pays it once for every shift it uses. Set objective.costs.per_route to the amount you want to pay to open a route, for example one hour of route time:

{
  "objective": {
    "costs": { "per_route_hour": 35, "per_travel_km": 0, "per_route": 35 }
  }
}

See Objective function for every cost term.

From weights to prices

V3 has no weights. Every objective term is a price in the objective’s currency: a fleet rate in objective.costs, or a price on the field itself (drop_cost, preferences[].violation_cost, assignment_costs[].cost, target.per_late_hour, time_windows[].per_late_hour). There is no conversion factor from a V2 weight to a price, so choose each price yourself: a price is the amount of route cost you accept to avoid the thing it prices. A price only has meaning next to the hourly rate it competes with (objective.costs.per_route_hour, 35 by default). Choose each price against the rate you use.

V2 input	V3 field
Route time (`weights.travelTimeWeight`)	`objective.costs.per_route_hour`
`options.minimizeResources: true`	`objective.costs.per_route`
`urgency`, with `plannedArrival`	`jobs[].target.per_late_hour`
`rankings[]` with `weights.rankingWeight`	`jobs[].assignment_costs[].cost`
`options.jobProximityRadius` with `weights.jobProximityWeight`	`objective.grouping.per_entry`, at most `1000` (a larger value is a `400`)
`weights.asapWeight`	`objective.per_delay_workday`, charged per served job per workday after the earliest. A positive rate below `0.00001` is a `400`

In V3 an unlisted vehicle in assignment_costs costs nothing, while V2 counts an unranked resource as ranking 100: give every vehicle an assignment_costs entry, with the most preferred vehicle at the smallest cost.

Response mapping

{
  "status": "SOLVED",
  "score": { "hardScore": 0, "mediumScore": 0, "softScore": -9900, "feasible": true },
  "trips": [
    {
      "resource": "truck-1",
      "date": "2026-04-01T00:00:00Z",
      "departureTime": "2026-04-01T06:00:00Z",
      "travelTime": 5400,
      "distance": 88000,
      "serviceTime": 900,
      "waitTime": 1800,
      "workTime": 8100,
      "start": {
        "job": "truck-1-start",
        "activity": "departure",
        "arrival": "2026-04-01T06:00:00Z",
        "breakTime": null,
        "location": { "latitude": 50.8503, "longitude": 4.3517 }
      },
      "end": {
        "job": "truck-1-end",
        "activity": "arrival",
        "arrival": "2026-04-01T08:45:00Z",
        "breakTime": null,
        "location": { "latitude": 50.8503, "longitude": 4.3517 }
      },
      "visits": [
        {
          "job": "delivery-1",
          "activity": "job",
          "arrival": "2026-04-01T07:00:00Z",
          "serviceTime": 300,
          "travelTime": 1800,
          "distance": 30000,
          "waitTime": 1800,
          "breakTime": 0,
          "location": { "latitude": 50.8798, "longitude": 4.7005 }
        },
        {
          "job": "delivery-2",
          "activity": "job",
          "arrival": "2026-04-01T07:55:00Z",
          "serviceTime": 600,
          "travelTime": 1200,
          "distance": 18000,
          "waitTime": 0,
          "breakTime": 1800,
          "location": { "latitude": 50.9000, "longitude": 4.5000 }
        }
      ]
    }
  ],
  "messages": [],
  "totalTravelTimeInSeconds": 5400,
  "totalTravelDistanceInMeters": 88000,
  "totalServiceTimeInSeconds": 900,
  "totalWaitTimeInSeconds": 1800
}

{
  "summary": {
    "score": {
      "violation_count": 0,
      "unassigned_priority": 0,
      "cost": 113.828,
      "components": {"routes": 0.0, "vehicles": 0.0, "time": 96.228, "distance": 17.6, "waiting": 0.0, "overtime": 0.0, "lateness": 0.0, "window_choice": 0.0, "target": 0.0, "tag_preference": 0.0, "reloads": 0.0, "grouping": 0.0, "workload_share": 0.0, "drop_costs": 0.0, "preferences": 0.0, "assignment": 0.0, "delay": 0.0}
    },
    "tasks": {"served": 2, "unassigned": 0, "unassigned_required": 0},
    "vehicles_used": 1,
    "shifts_used": 1,
    "distance_m": 88000,
    "time": {"span_s": 9900, "travel_s": 5400, "service_s": 900, "depot_s": 0, "wait_s": 1800, "break_s": 1800, "overtime_s": 0},
    "timings": {"search_ms": 1020, "total_ms": 1087},
    "search": {"termination": "time_limit", "iterations": 48210}
  },
  "routes": [
    {
      "vehicle": "truck-1",
      "shift": "mon",
      "distance_m": 88000,
      "time": {"span_s": 9900, "travel_s": 5400, "service_s": 900, "depot_s": 0, "wait_s": 1800, "break_s": 1800, "overtime_s": 0},
      "stops": [
        {
          "type": "start",
          "location": [4.3517, 50.8503],
          "arrival": "2026-04-01T08:00:00+02:00",
          "departure": "2026-04-01T08:00:00+02:00",
          "service_s": 0
        },
        {
          "type": "job",
          "id": "delivery-1",
          "location": [4.7005, 50.8798],
          "arrival": "2026-04-01T08:30:00+02:00",
          "service_start": "2026-04-01T09:00:00+02:00",
          "departure": "2026-04-01T09:05:00+02:00",
          "wait_s": 1800,
          "service_s": 300,
          "travel_s": 1800,
          "distance_m": 30000,
          "lateness_s": 0
        },
        {"type": "break", "arrival": "2026-04-01T09:05:00+02:00", "departure": "2026-04-01T09:35:00+02:00", "service_s": 1800},
        {
          "type": "job",
          "id": "delivery-2",
          "location": [4.5, 50.9],
          "arrival": "2026-04-01T09:55:00+02:00",
          "service_start": "2026-04-01T09:55:00+02:00",
          "departure": "2026-04-01T10:05:00+02:00",
          "wait_s": 0,
          "service_s": 600,
          "travel_s": 1200,
          "distance_m": 18000,
          "lateness_s": 0
        },
        {
          "type": "end",
          "location": [4.3517, 50.8503],
          "arrival": "2026-04-01T10:45:00+02:00",
          "departure": "2026-04-01T10:45:00+02:00",
          "wait_s": 0,
          "service_s": 0,
          "travel_s": 2400,
          "distance_m": 40000
        }
      ]
    }
  ],
  "plan": {
    "routes": [
      {
        "vehicle": "truck-1",
        "shift": "mon",
        "stops": [
          {"type": "job", "id": "delivery-1"},
          {"type": "job", "id": "delivery-2"}
        ]
      }
    ]
  },
  "unassigned": []
}

Both examples describe the same route: a 30-minute wait for the first window, a 30-minute break after the first job, and a V3 request that set no objective.

Routes and stops

V2	V3	Notes
`trips[]`	`routes[]`	One entry per vehicle shift that serves something
`trips[].resource`	`routes[].vehicle`	The vehicle `id`
(none)	`routes[].shift`	The shift `id` the route runs on
`trips[].travelTime`	`routes[].time.travel_s`	Driving time only
`trips[].distance`	`routes[].distance_m`
`trips[].workTime`	`routes[].time.span_s`	Not identical: V2 sums service, travel and waiting; V3 reports the span from start to end, which also includes breaks
`trips[].date`, `departureTime`	the `start` stop’s `arrival`
`trips[].start`, `trips[].end`	`start` and `end` stops inside `stops[]`
`trips[].visits[]`	`routes[].stops[]`	Typed, see below
`visits[].job`	`stops[].id`
`visits[].activity`	`stops[].type`
`visits[].arrival`	`stops[].service_start`	The service start. See the warning below
`visits[].serviceTime`	`stops[].service_s`	On a resumable job paused by a break, V2 adds the pause; V3 reports it apart, in `break_s`
`visits[].travelTime`, `distance`	`stops[].travel_s`, `distance_m`	From the previous stop
`visits[].waitTime`	`stops[].wait_s`
`visits[].breakTime`	a separate `break` stop, or the stop’s `break_s`	The break sits before the visit it delayed, and its `service_s` is the break length. A break that paused a resumable job has no stop of its own and is the job stop’s `break_s`
`visits[].location`	`stops[].location`	`[longitude, latitude]`
a visit with `activity: "DEPOT"`	a `reload` stop	A mid-shift return to a depot. V2 names the visit after the depot’s `name`; V3 gives the depot id in `depot`
`visits[].snappedLocation`, `latlon`	`stops[].snapped_location`	`[longitude, latitude]`. V2 `latlon` is `[latitude, longitude]`

arrival means different things. V2 visits[].arrival is the service start: the arrival plus any waitTime. V3 stops[].arrival is the physical arrival, before waiting, and the service start is stops[].service_start (arrival + wait_s unless a break is taken on arrival). V2 visits have no departure field; V3 adds departure, the end of service.

stops[].type takes seven values, and a client must handle all of them:

`type`	Meaning	Carries
`start`	Departure from the shift’s start	`depot` when the shift start names a depot
`job`	A served job	`id`
`pickup`, `delivery`	The two legs of a shipment	`id` of the leg: its own, or `<shipment>:pickup` and `<shipment>:delivery`
`break`	A driver break	No `id` and no `location`
`reload`	A mid-shift return to a depot that starts a new trip	`depot`, no `id`
`end`	Arrival at the shift’s end	`depot` when the shift end names a depot

A break stop appears for each break a route takes, and a reload stop for each mid-shift return to a depot. V2 reports a reload as a visit with activity: "DEPOT" and has no visit for a break.

Summary, score and unassigned jobs

V2	V3	Notes
`status: "SOLVED"`	`summary.tasks`	`served`, `unassigned` and `unassigned_required`. Read completeness from `unassigned[]`, which has one entry per job or shipment left out
`score.hardScore`, `softScore`, `feasible`	`summary.score`	`violation_count`, `unassigned_priority`, `cost`, and `components` that itemise `cost` in currency
`totalTravelTimeInSeconds`	`summary.time.travel_s`	Driving time only
`totalTravelDistanceInMeters`	`summary.distance_m`
`totalServiceTimeInSeconds`, `totalWaitTimeInSeconds`	`summary.time.service_s`, `summary.time.wait_s`	Summed over routes; per route in `routes[].time`
`unserved` + `unservedReasons`	`unassigned[]`	Objects with `task`, `category`, `reasons[]` of `{ "constraint", "message" }`, and `relaxations[]`. A shipment is one entry under its shipment id, where V2 lists both job names. V2 reasons are all-caps codes such as `TIME_WINDOW_VIOLATED` or `CAPACITY_EXCEEDED`; V3 publishes no outcome code, so read `category` and the rules in `reasons[].constraint`
`messages[]`	(none)
`suggestions[]`	`suggestions[]` on the suggest response	Different shape. See Suggest response

New in V3: summary.tasks.served, tasks.unassigned, vehicles_used, timings.total_ms, and a top-level plan that mirrors routes in the request’s vocabulary. Send that plan back unchanged to evaluate, to suggest, or to solve as a warm start. unassigned[].category says what kind of miss it is: impossible (no vehicle can ever serve it), blocked (it does not fit alongside the jobs that were served), priced_out (its drop_cost was cheaper than serving it) or time_limit (a feasible position exists but was not found in the time budget).

Suggest response

V2 returns one suggestions[] entry per alternative, each with a score and its assignments[]. V3 returns one suggestions[] entry per task outside plan, with that task’s alternatives as ranked insertions[], best first. Tasks linked by a relation are placed together and share one entry.

V2 `suggestions[].assignments[]`	V3 `suggestions[].insertions[]`	Notes
`job`	`suggestions[].task`	The task the entry is about. For tasks placed together, the first `sequence` member, else the first in problem order (`jobs`, then `shipments`)
`resource`	`placements[].vehicle`, `placements[].shift`	The `plan.routes[]` entry the stop goes into, by vehicle id and shift id
`suggestedArrival`	`placements[].arrival`	In the UTC offset of the shift’s `from`
`latestArrival`	`placements[].latest_arrival`	The latest arrival that keeps the rest of the route feasible
`executedAfter`	`routes[].stops`	V3 returns every route the insertion changes, whole, with the new stops in: the stop before a placement is its predecessor there. Swap these routes into `plan` to apply the insertion
`score`	`delta`	`{ cost, distance_m, travel_s }`: the change against the plan you sent, not a score of the whole plan. What two `/evaluate` calls would differ by, with `cost` in your currency and `travel_s` driving time only
`scoreExplanation`, `violations`	(none)	V3 lists feasible placements only
`suggestedInitialArrival`	(none)
several `assignments[]` in one suggestion	`insertions[].placements[]`	One entry per stop the insertion adds, in route order: both legs of a shipment, or every member of a relation. A single job has one

New in V3: suggestions[].reason (code and message) when insertions is empty, placements[].service_start (when service starts, after any wait), insertions[].interchangeable_vehicles, and the top-level truncated and timings.total_ms. See Suggest for every field.

V2 fields with no direct V3 equivalent

The fields below have no one-to-one V3 field. The right-hand column is what to send in V3 instead, or says that there is no equivalent.

Top-level fields

V2 field	In V3
`costs` (cost configuration)	`objective.costs`: set `per_route_hour`, `per_travel_km`, `per_wait_hour`, `per_overtime_hour` and `per_route` directly; lateness is `objective.per_late_hour`
`weights`, except `rankingWeight`, `travelTimeWeight`, `asapWeight` and `jobProximityWeight`	No weights. Each objective term is a currency rate in `objective.costs` or a price on the field itself (`drop_cost`, `violation_cost`, `target.per_late_hour`). See From weights to prices
`weights.jobProximityWeight`	`objective.grouping.per_entry`, a price you choose, between `0` and `1000`, together with `objective.grouping.radius_m`
`weights.asapWeight`	`objective.per_delay_workday`, a price you choose, charged per served job per workday after the earliest. A positive rate below `0.00001` is a `400`, as is a rate whose total over the later workdays exceeds `21474.83647`
`customDistanceMatrices`	No equivalent
`hook`, `label`	No equivalent

Resource and shift fields

V2 field	In V3
`category`	`vehicles[].profile`: `car`, `truck` or `bike`. Without it every vehicle is routed as a car
`maxDriveDistance`	`vehicles[].limits.max_distance_m`
`maxDriveTimeInSeconds`, `maxDriveTime`	No cap on total driving time. `limits.max_route_duration_s` caps the whole route span (travel, service and waiting)
`shifts[].overtime` (deprecated boolean)	`shifts[].max_overtime_s`, in seconds
`hourlyCost`	`vehicles[].costs.per_route_hour`: it replaces the fleet rate `objective.costs.per_route_hour` for that vehicle and is reported under `components.time`
`region`	No geographic region. Label jobs with `tags` and set `vehicles[].preferred_tags[]` with a `violation_cost`
`loadCompatibility`	No equivalent
`rules[]` work, service, drive and complexity limits	See Period rules
`shifts[].jobTypeLimitations`	A `quotas[]` entry whose window holds the stops’ service starts
`shifts[].unloadBeforeEndShift`	No equivalent
`deductPreviousBreaks` (any break type)	No V3 counterpart: model each accumulation window as its own break
`UNAVAILABILITY` break `location`	No equivalent

Job fields

V2 field	In V3
`tags[]` without `hard: true`, and `tags[].weight`	See Tags
`windows[].hard`, `windows[].weight`	`time_windows[].per_late_hour`
`plannedArrival` without a positive `urgency`	`target`, with a `per_late_hour` you choose. See Planned arrival and urgency
`urgency` without `plannedArrival`	No equivalent
`plannedDate`	Not supported: V3 has no soft day preference, and `preferred_date` or `objective.non_preferred_date_cost` is a `400` (`unknown_field`). For a hard date, limit `time_windows` to that day
`hard`, `hardWeight`	A job is must-serve unless it carries a `drop_cost`
`padding`	No equivalent
`complexity`	No equivalent
`initialDepot`	A `{ "type": "reload", "depot": "<depot id>" }` stop in the `plan` route
`initialResource` on a resource’s second or later shift	`plan.routes[].shift`. See Existing plans

Relation fields

V2 field	In V3
`maxWaitingTime`	`synchronized.max_spread_s`
`minTimeInterval`, `maxTimeInterval` on `DIRECT_SEQUENCE`	One `time_lag` per consecutive pair. See Relations
`hardMinWait`	No equivalent. Time bounds are hard
`weight`	No equivalent. Relations are hard
`partialPlanning` on relations other than `SAME_TIME`	V3 relations bind the members that are served, as with `partialPlanning: true`; these relation types have no all-or-nothing form, except a `SAME_TRIP` chain over a pickup-and-delivery pair (an `all_or_none` over one `consecutive` chain, with or without a shipment). On `SAME_TIME`, `false` (the default) means all-or-nothing: add an `all_or_none` relation. See Relations

Depot fields

V2 field	In V3
`name`	`depots[].id`
`cost`	`depots[].per_reload`
`windows`	No depot opening hours
`capacity`	Not mapped. Set `depots[].max_intake` instead, from the site’s real limit: V2 sums the `load` of the jobs that pick the depot, while `max_intake` counts the whole truckload tipped there. In V2 `0` means the depot does not unload that dimension; in V3 it means a truck carrying it cannot tip there. See Multi-trip reloads

Option fields

V2 field	In V3
`routingEngine`	`problem.travel.engine`: `tomtom`, `osm` or `tomtom_real_time` (not enabled yet: a request that sets it is rejected with `403`). Without it the engine is `osm`, or `tomtom` when `departure_time` is set. `GOOGLE` and `ANYMAP` have no V3 value
`euclidian`	`problem.travel.engine: "straight_line"`, with an optional `problem.travel.speed_kmh` (`1` to `1000`, default `50`). Travel is the great-circle distance at that speed, with no road network. `straight_line` cannot be combined with `departure_time`, `options.polyline` or a vehicle `profile` other than `car`. See Distance matrices
`traffic`	`problem.travel.departure_time` for time-of-day traffic, or `vehicles[].speed_factor` to scale travel times. Travel time is divided by `speed_factor`, so V2 `traffic: 1.1` is a `speed_factor` of about `0.91`.
`polylines`	`options.polyline`
`partialPlanning`	Always on
`snapUnit`	No V3 equivalent
`explanation`	Not needed: `unassigned[]` always carries reasons, and `evaluate` returns `violations[]`
`fairWorkloadPerResource`, `workloadSensitivity`	`objective.workload_share` (`per_imbalance_hour`, `tolerance`). Give a part-time vehicle a smaller share with `vehicles[].workload_weight`. You set the price directly; V2’s `workloadSpreadWeight` has no equivalent
`fairWorkloadPerTrip`, `fairComplexityPerTrip`, `fairComplexityPerResource`	No equivalent
`enableClustering`, `clusteringThresholdMeters`	No equivalent
`onlyFeasibleSuggestions`	Suggest returns feasible insertions only
`curbside`, `snapPoints`	No equivalent

Feature parity

Feature	V2	V3	V3 mechanism
Capacity	Yes	Yes	Named `capacity` and `pickup_load` maps, up to 4 dimensions (V2: 5). A fifth is a `400`
Hard time windows	Yes	Yes	`time_windows[]`
Multiple time windows per job	Yes	Yes	Optional `time_windows[].choice_cost` to rank them
Soft time windows	Yes	Yes	`time_windows[].per_late_hour` (late side, single-window tasks) or fleet-wide `objective.per_late_hour`
Planned arrival with urgency	Yes	Partial	`target` prices late arrival only
Skills (hard tags)	Yes	Yes	`required_skills[]`
Skill levels	No	Yes	`required_skills[].min_level` and `vehicles[].skills[].level`
Soft tags	Yes	Partial	`preferences[]` per vehicle; no per-tag weight
Proficiency	Yes	Yes	`jobs[].service_factors[]`, `vehicles[].service_factor`, `shifts[].service_factor`
Resource ranking	Yes	Yes	`assignment_costs[]`
Allowed and disallowed resources	Yes	Yes	`eligible_vehicles`
Planned resource	Yes	Yes	`eligible_vehicles.allowed` with one id
Job priority	Yes	Yes	`priority`
Optional jobs	Yes	Yes	`drop_cost`
Relations	Yes	Partial	`sequence`, `consecutive`, `tag_order`, `same_vehicle`, `same_day`, `same_route`, `synchronized`, `time_lag`, `compatible_vehicles`, `all_or_none`. `NEIGHBOR` has no equivalent; all-or-nothing for jobs tied by `synchronized` or `time_lag`, and for a `SAME_TRIP` chain over a pickup-and-delivery pair (`partialPlanning: false`)
Pickup and delivery	Yes	Yes	`shipments[]`
Maximum distance	Yes	Yes	`limits.max_distance_m`
Maximum drive time	Yes	Partial	`limits.max_leg_travel_s` caps a single leg (V2 `maxDriveTimeJob`). There is no cap on a route’s total driving time; `limits.max_route_duration_s` caps the route span instead
Overtime	Yes	Yes	`shifts[].max_overtime_s` and `objective.costs.per_overtime_hour`
Driver breaks	Yes	Yes	Windowed, drive-time, duty-time and fixed breaks
Multi-trip reloads	Yes	Yes	`depots[]` and `shifts[].reloads`
Depot opening hours	Yes	No
Multi-day planning	Yes	Yes	One `shifts[]` entry per working day; `time_windows` and `same_day` steer the day. There is no soft day preference (`preferred_date` is not supported)
Jobs without a location	Yes	Yes	Omit `location`
Period rules	Yes	Partial	`quotas[]` and `limits.periods[]`. No minimums, no service-only or drive-only caps
Workload balancing	Yes	Partial	`objective.workload_share` balances service time per vehicle. No per-trip or complexity balancing
Job proximity	Yes	Yes	`objective.grouping`
Route clustering	Yes	No
Custom distance matrix	Yes	No
Routing engine choice	Yes	Partial	`travel.engine`: `tomtom`, `osm` or `straight_line` (V2 `euclidian`); `tomtom_real_time` is not enabled yet. No `GOOGLE` or `ANYMAP`
Vehicle profile	Yes	Yes	`vehicles[].profile`: `car`, `truck`, `bike`
Route polylines	Yes	Yes	`options.polyline`
Warm start	Yes	Yes	`plan`, with `locked_count` to freeze dispatched stops
Evaluate	Yes	Yes	`POST /v3/routing/evaluate`
Suggest	Yes	Yes	`POST /v3/routing/suggest`
Job lifecycle (submit, poll, change)	Yes	Solve only: submit, poll, result, cancel	`/v3/routing/runs`. See Endpoints and lifecycle
Validate without solving	No	Yes	`POST /v3/routing/validate/solve`
Departure-time traffic	No	Yes	`travel.departure_time`
Per-vehicle costs	Yes	Yes	`vehicles[].costs` (and `shifts[].costs`): `per_route`, `per_route_hour`, `per_travel_km`, `per_wait_hour`, `per_overtime_hour`, each replacing the fleet value; `per_used_vehicle` on `vehicles[].costs` only

Quickstart

Send your first native V3 request.

The V3 API model

The full request and response model.

Constraints

Every constraint field, with examples.

Errors

The error body and its codes.

Field service day

A worked V3 example: one solve, then evaluate and suggest on the same data.

Suggest

Rank insertion positions for new tasks.

​Overview

​How to port a request

​Endpoints and lifecycle

​Existing plans

​Conventions

​Request mapping

​Vehicles (resources)

​Shifts

​Breaks

​Depots (multi-trip reloads)

​Jobs

​Time windows

​Tags

​Priority and optional jobs

​Planned arrival and urgency

​Relations

​Pickup and delivery pairs

​Period rules

​Options

​Default objective

​From weights to prices

​Response mapping

​Routes and stops

​Summary, score and unassigned jobs

​Suggest response

​V2 fields with no direct V3 equivalent

​Top-level fields

​Resource and shift fields

​Job fields

​Relation fields

​Depot fields

​Option fields

​Feature parity

Quickstart

The V3 API model

Constraints

Errors

Field service day

Suggest

Overview

How to port a request

Endpoints and lifecycle

Existing plans

Conventions

Request mapping

Vehicles (resources)

Shifts

Breaks

Depots (multi-trip reloads)

Jobs

Time windows

Tags

Priority and optional jobs

Planned arrival and urgency

Relations

Pickup and delivery pairs

Period rules

Options

Default objective

From weights to prices

Response mapping

Routes and stops

Summary, score and unassigned jobs

Suggest response

V2 fields with no direct V3 equivalent

Top-level fields

Resource and shift fields

Job fields

Relation fields

Depot fields

Option fields

Feature parity