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. Solvice maintains a V2-to-V3 compatibility mapping: a translation of a V2 request body into a V3 one. The tables below follow that mapping, so the V3 column shows what a V2 field means in V3 terms. The mapping does not cover every V2 field: V2 fields that are not carried over lists the ones it leaves out and what to send natively instead.

Every statement on this page about “the compatibility mapping” describes the translation of a V2 request into a V3 one: what the translated request keeps and what it loses. The page makes no statement about how a call to a V2 endpoint is processed. Use those statements to decide what to write in the native V3 request.

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 does not carry over

Check every field your V2 request sends against V2 fields that are not carried over. A field in that list has no automatic translation, 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 with ?validate_only=true. 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 300), 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" }
        ]
      }
    ]
  }
}

When a V2 request is translated by the compatibility mapping, the plan it builds from initialResource and initialArrival is narrower than a native plan:

First shift only. Every job with an initialResource is placed on that resource’s first shift, ordered by initialArrival. On a solve, a plan that spans several days is therefore folded onto the first day without an error. On evaluate and suggest, a resource that has more than one shift and at least one job with initialResource is rejected with 400. Natively, plan.routes[].shift names the shift of each route.
Order only. initialArrival decides the order of the stops. The arrival time itself is not carried over: V3 recomputes every time from the stop order. A job without an initialArrival sorts after the timed ones, by its position in the first SEQUENCE relation that lists it.
Nothing is frozen. The mapping sets no locked_count. Natively, set locked_count on a plan route to freeze its first stops.
Skipped entries. On a solve, an initialResource that names no resource in the request is left out, and so is one that contradicts a plannedResource or a relation’s resource on the same job. On evaluate and suggest each of those is a 400. So is a job that has an initialResource but no initialArrival, when it is in no SEQUENCE relation, and so is a resource whose committed jobs mix timed and untimed jobs, or take their position from different SEQUENCE relations. Order a resource’s committed jobs either by initialArrival on every job or by one SEQUENCE relation.
No shipments. When any job in the request carries initialResource, no PICKUP_AND_DELIVERY pair is turned into a shipment. On suggest, a request that combines initialResource with a pair still to be placed is rejected with 400. See Pickup and delivery pairs.
initialDepot is not read. Natively, a reload is a { "type": "reload", "depot": "<depot id>" } stop in the plan route.

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 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`, also when a V2 request with five positions is translated by the compatibility mapping
Check a request without solving	Not available	`?validate_only=true` on all three endpoints

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`. 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`. Not carried over by the compatibility mapping, so set it 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

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. limits.max_leg_travel_time_s takes the place of maxDriveTimeJob: a cap on any single travel leg. 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`	Not carried over by the compatibility mapping. State the allowed overtime in seconds
`ignoreTravelTimeToFirstJob`	`ignore_start_leg`	The leg from `start` to the first task costs nothing
`ignoreTravelTimeFromLastJob`	`ignore_end_leg`	The leg from the last task to `end` costs nothing
`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, "windows": [{ "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 one `windows` entry	`duration` becomes `duration_s`. The window bounds the break’s start, and `to` is a hard latest start. When a V2 request is translated by the compatibility mapping, `to` is widened to the end of the shift. An optional `location` carries over
`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, and the compatibility mapping carries each depot’s duration over as its service_duration_s.
cost becomes cost_per_visit, charged once per reload. The compatibility mapping does not carry it over.
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": { "weight": 10 },
  "priority": 2,
  "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` (named map)	`[10]` becomes `{ "weight": 10 }`
`windows[]`	`time_windows[]`	See Time windows
`tags[]` with `hard: true`	`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 ranked vehicle. V2 charges the rank of the resource that serves the job, so `cost` is the price of serving it on that vehicle: give the best-ranked vehicle the lowest `cost`. A vehicle without an entry costs `0` natively, where V2 counts an unranked resource as rank `100`. 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`	`locked_vehicle`	Hard pin to one vehicle. An id that matches no vehicle is a `400` natively; the compatibility mapping leaves such a pin out instead
`allowedResources`	`eligible_vehicles.allowed`	Hard whitelist
`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[].job_ids`	No job field. See Period rules

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. When a V2 request is translated by the compatibility mapping, neither windows[].hard nor windows[].weight is read, so every window the mapping produces is hard. A job can list several windows and is served in one of them. An optional time_windows[].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_fee`
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.unserved_priority`	`summary.score.components.drop_fees`
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, and when a V2 request is translated by the compatibility mapping, exactly that product (duration in seconds) is sent as the V3 priority. Do the same to keep V2’s ranking, or send your own rank if job length should not count. priority and drop_fee 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": "end" measures the end of service instead of the arrival.

When a V2 request is translated by the compatibility mapping, a target is produced only for a job that sends both plannedArrival and an urgency greater than 0:

V2 job sends	Result of the mapping
`plannedArrival` and `urgency` > `0`	`target` at `plannedArrival`, measured at arrival, with `per_late_hour` = `urgency / 100000`
`plannedArrival` without `urgency`, or with `urgency: 0`	Not carried over. The job has no target
`urgency` without `plannedArrival`	Not carried over. V3 has no “schedule earlier in the day” preference
`weights.plannedWeight`, `weights.urgencyWeight`	Not read

The mapping’s price is on its own scale, in which route time costs 0.036 per hour. See From weights to prices before you reuse the value next to a different hourly rate.

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. With more than one vehicle the compat path also adds a zero-minimum `time_lag` per consecutive pair, so members on different vehicles keep their order (solver2 scores a plain SEQUENCE across resources); write both when migrating by hand
`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": "end"` on `from`. The two jobs may be on different vehicles. Jobs only, not shipments
`FIRST_JOB`	`sequence`	One single-job `sequence` per listed job: each job is pinned as the first stop of its route, with no order between the jobs. A `SEQUENCE` of one job means the same
`DIRECT_SEQUENCE`	`sequence` + `same_vehicle`	Approximation: same vehicle and same order, but other stops may be scheduled in between. There is no “directly consecutive” relation. `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`	One shift of one vehicle, as in V2; reloads within the shift do not split it. `stops`, or a `tag`. Jobs only, not shipments
`SAME_TIME`	`synchronized` + `all_or_none`	`stops` plus a required `max_wait_s` (`0` means simultaneous), taken from `maxTimeInterval`. Add an `all_or_none` over the same `stops` unless the V2 relation sets `partialPlanning: true`. `timeInterval: FROM_DEPARTURE` becomes `"on": "end"`. 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	The compatibility mapping rejects it with `400`

{
  "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 locked_vehicle on each job instead. Relation fields that change meaning:

SAME_TIME tolerance. The V2 reference documents maxWaitingTime (default 1200 seconds). When a V2 request is translated by the compatibility mapping, maxTimeInterval is read instead, and without it the tolerance is 0 seconds. Natively, max_wait_s is required.
SAME_TIME with minTimeInterval on three or more jobs is rejected by the compatibility mapping (400). Write one time_lag per pair natively.
DIRECT_SEQUENCE time intervals. V2 applies minTimeInterval and maxTimeInterval to DIRECT_SEQUENCE as well as to SEQUENCE. The compatibility mapping carries them over for SEQUENCE only: on a DIRECT_SEQUENCE relation both bounds are left out without an error. Natively, 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": "end" 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.
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, and the V2 endpoints add an all_or_none relation for it. To keep that in V3, add an all_or_none relation over the same stops next to the synchronized one. all_or_none only takes jobs that a synchronized or time_lag relation also names, 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_fee, skills, eligible_vehicles, locked_vehicle, preferences and service_factors. They apply to the pair.
The shipment id must be unique across jobs and shipments.

When a V2 request is translated by the compatibility mapping, the two jobs do not contribute equally:

pickup, priority, service_factors (from proficiency) and eligible_vehicles (from allowedResources and disallowedResources) are taken from the pickup job. The delivery job’s load, priority, proficiency and resource lists are not carried over.
Tags with "hard": true on either job become skills of the shipment.
locked_vehicle comes from the relation’s resource. A plannedResource on either job is not carried over.
rankings on either job are not carried over.

The mapping turns a pair into a shipment only when the relation lists exactly two jobs, both have a location, neither appears in another relation, neither carries a GROUP_SEQUENCE tag or a plannedArrival with a positive urgency, and no job in the request carries initialResource. Any other pair stays two jobs with a sequence and a same_vehicle relation.

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", "job_ids", "max_tasks" }`, where `job_ids` 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_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_duration_s, max_distance_m and max_tasks. A shipment counts as two stops toward max_tasks. See Constraints. When a V2 request is translated by the compatibility mapping, only jobTypeLimitations (with period and groupTag) is enforced. The work, service, drive and complexity limits are not.

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 `1`, maximum `300`. A larger value is a `400`. A value below `0.1` asks for the minimum search time of 100 ms
`options.solvingTime` (seconds)	`options.time_limit_s`	The same budget in seconds. On the V2 endpoints the precedence is `?millis`, then `solvingTime`, then the default of 1000 ms. Natively there is a single field
`options.minimizeResources`	`objective.costs.fixed`	See Default objective
`options.jobProximityRadius`	`objective.grouping.radius_m`	`objective.grouping` also requires `cost_per_reentry`, a currency amount between `0` and `1000`
`options.jobProximityDistanceType`	`objective.grouping.distance`	`HAVERSINE` becomes `straight_line` (the default), `REAL` becomes `road`
`options.maxSuggestions`	`options.max_suggestions` on suggest	The default differs. The V2 reference documents `0` (every placement) as the default and `5` as the maximum. V3 returns `5` insertions per task when the field is omitted, every feasible placement for `0`, and caps a positive value at `100`. Send `0` explicitly to keep the V2 default. A V2 request translated by the compatibility mapping gets the V3 default of `5` when it omits the option
`options.routingEngine`	`problem.travel.engine`	`TOMTOM` becomes `tomtom` (the default) and `OSM` becomes `osm`. `GOOGLE` and `ANYMAP` have no V3 value. Not carried over by the compatibility mapping, so set it yourself
`options.polylines`	`options.polylines`	`"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[]`

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 not optimized for the same thing as a V2 request translated by the compatibility mapping. The mapping always sets an explicit objective; a native request without one gets the V3 defaults. Amounts are in the objective’s currency.

	V2 request translated by the compatibility mapping	Native V3 request without `objective`
Time	Route time is the only fleet-wide priced term, at `per_route_hour: 0.036`	35 per hour of route span (travel, service, waiting and breaks)
Distance	Free (`per_travel_km: 0`)	0.20 per kilometre
Vehicles used	Free (`fixed: 0`), or `0.036` per used vehicle when `options.minimizeResources` is `true`	Free, unless you set `objective.costs.fixed` or a vehicle’s `costs.fixed`
Waiting, overtime, lateness	Not priced separately; `weights` for them are not read	Not priced separately until you set `per_wait_hour`, `per_overtime_hour` or `per_late_hour`

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

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

For minimizeResources: true, the compatibility mapping charges each used vehicle the equivalent of one hour of route time. Natively, set objective.costs.fixed to your hourly rate:

{
  "objective": {
    "costs": { "per_route_hour": 35, "per_travel_km": 0, "fixed": 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_fee, preferences[].violation_cost, target.per_late_hour, time_windows[].per_late_hour). No V2 weight is converted for you when you write a request natively, 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. When a V2 request is translated by the compatibility mapping, route time is priced at 0.036 per hour, which is 0.00001 per second, and the mapping derives a few other prices on that same scale:

V2 input	V3 field	Value the mapping sends
Route time	`objective.costs.per_route_hour`	`0.036`
`options.minimizeResources: true`	`objective.costs.fixed`	`0.036`, the cost of one hour of route time
`urgency`, with `plannedArrival`	`jobs[].target.per_late_hour`	`urgency / 100000`
`rankings[]` with `weights.rankingWeight`	`jobs[].assignment_costs[].cost`	`rankingWeight / travelTimeWeight / 100000 × ranking` per ranked resource
`options.jobProximityRadius`	`objective.grouping.cost_per_reentry`	`0.003` by default. `weights.jobProximityWeight` is not read

For rankings[], rankingWeight counts as 1 when the request sends no weights object and as 0 when weights is sent without it; travelTimeWeight counts as 1 when it is absent or not positive; and ranking is limited to the range 1 to 100. The price is charged for the resource that serves the job, as in V2. A resource the job does not list counts as rank 100; the mapping applies that default itself, so it is not written into the request. A job whose listed resources all have the same ranking is still charged, because the absolute price is what makes a job ranked 100 everywhere the first one dropped under capacity pressure. Nothing is charged when the job has no rankings, when rankingWeight is 0, or when the rate is so small that the rank-100 price rounds to zero. All other V2 weights are not read. These values keep their meaning only next to per_route_hour: 0.036. To keep the same trade-off at another hourly rate, multiply each of them by per_route_hour / 0.036. At the V3 default of 35 per hour that factor is about 972: an urgency of 100 is 0.001 per late hour on the mapping’s scale and 0.97 per late hour next to a rate of 35. objective.grouping.cost_per_reentry follows the same rule: at 35 per hour the rescaled default of 0.003 is about 2.9. It accepts at most 1000, and a larger value is a 400.

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": {
      "violations": 0,
      "unserved_priority": 0,
      "cost": 113.828,
      "components": {"fixed": 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, "depot_visits": 0.0, "grouping": 0.0, "drop_fees": 0.0, "other": 0.0}
    },
    "tasks": {"served": 2, "unserved": 0, "unserved_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}
  },
  "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",
          "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",
          "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",
          "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[].arrival` plus `wait_s`	See the warning below
`visits[].serviceTime`	`stops[].service_s`
`visits[].travelTime`, `distance`	`stops[].travel_s`, `distance_m`	From the previous stop
`visits[].waitTime`	`stops[].wait_s`
`visits[].breakTime`	a separate `break` stop	The break sits before the visit it delayed, and its `service_s` is the break length
`visits[].location`	`stops[].location`	`[longitude, latitude]`
`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, so the service start is arrival + wait_s. 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`. `location` is absent when the break is taken en route
`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 has no reload visit: a V2-shaped response leaves those stops out.

Summary, score and unassigned jobs

V2	V3	Notes
`status: "SOLVED"`	`summary.tasks`	`served`, `unserved` and `unserved_required`. Read completeness from `unassigned[]`, which has one entry per job or shipment left out
`score.hardScore`, `softScore`, `feasible`	`summary.score`	`violations`, `unserved_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 `job_id`, `category`, `reasons[]` of `{ "code", "message" }`, and `relaxations[]`
`messages[]`	(none)
`suggestions[]`	`suggestions[]` on the suggest response	Different shape. See Suggest response

New in V3: summary.tasks.served, tasks.unserved, 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_fee was cheaper than serving it) or search_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[].job_id`	The task the entry is about. For tasks placed together, the first of them
`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, duration_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 `duration_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 reason when insertions is empty, insertions[].interchangeable_vehicles, and the top-level truncated and elapsed_ms. See Suggest for every field.

What a V2-shaped response contains

When a V2 request is translated by the compatibility mapping and solved, the V2-shaped response that comes back is filled as follows.

Populated: status (always SOLVED), score, messages, unserved, unservedReasons, the four totals, and per trip resource, date, departureTime, travelTime, distance, serviceTime, waitTime, workTime, start, end and visits[]. Every visit carries job, arrival, serviceTime, travelTime, distance, waitTime, breakTime, activity, location, snappedLocation and latlon.
score: hardScore and mediumScore are 0 and feasible is true on a solve, because a job that cannot be served is returned in unserved instead of producing an infeasible plan. softScore is the negated sum of the time, distance, waiting, overtime and drop-fee cost components, in units of 1/100,000 of the objective’s currency, so compare it only with other scores from the same request. On evaluate, hardScore is the negated number of violations, feasible is false when there are any, and softScore is 0.
unservedReasons: the values are reason codes such as TIME_WINDOW_VIOLATED or CAPACITY_EXCEEDED, not sentences.
messages: warnings about parts of the request that were accepted but not enforced, for example a rule whose period overlaps no shift.
Suggest: every assignment carries job, resource, suggestedArrival, latestArrival, executedAfter, suggestedInitialArrival (equal to suggestedArrival), score and an empty violations. scoreExplanation is not returned.
Not returned: id, occupancy, estimatedCost, unresolved, violations, workloadFairness, trips[].polyline, trips[].occupancy, and depot reload visits.

V2 fields that are not carried over

The compatibility mapping does not read the fields below, except deductPreviousBreaks, whose row says where it is honoured. When a V2 request that sends them is translated by the mapping, they are left out without an error, so the translated request is solved as if they were absent. The right-hand column is what to send when you write the request natively.

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 `fixed` directly; lateness is `objective.per_late_hour`
`weights`, except `rankingWeight` and `travelTimeWeight`	No weights. Each objective term is a currency rate in `objective.costs` or a price on the field itself (`drop_fee`, `violation_cost`, `target.per_late_hour`). See From weights to prices
`weights.jobProximityWeight`	`objective.grouping.cost_per_reentry`. The mapping applies `0.003` by default when `jobProximityRadius` is set
`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`
`maxDriveTimeJob`	`vehicles[].limits.max_leg_travel_time_s`: a cap on any single travel leg. A value of `0` or below capped nothing in V2; leave the field out
`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
`compatibleResources` (with `enforceCompatibility` on a relation)	`vehicles[].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. The V2 endpoints translate it for you: `[]` becomes the vehicle’s own id, because V3 rejects an empty list, and names that are no resource are dropped. Without a list a vehicle pairs with any vehicle
`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 native V3 field. The V2 compatibility mapping honours it on `DRIVE` and `DUTY` breaks and ignores it on `WINDOWED`
`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`	`preferred_date` with `objective.non_preferred_date_cost` (a soft preference). For a hard date, limit `time_windows` to that day
`hard`, `hardWeight`	A job is must-serve unless it carries a `drop_fee`
`padding`	No equivalent
`complexity`	No equivalent
`resumable`	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`. The mapping places every such job on the first shift. See Existing plans

Relation fields

V2 field	In V3
`maxWaitingTime`	`synchronized.max_wait_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`	V3 relations bind the members that are served, as with `partialPlanning: true`. For `false` (the V2 default) on `SAME_TIME`, add an `all_or_none` relation over the same `stops`; other relation types have no all-or-nothing form. See Relations
`enforceCompatibility`	A `compatible_vehicles` relation over the same `stops`, next to its `synchronized` relation. The V2 endpoints add it when `enforceCompatibility` is `true`, the relation has two or more jobs and at least one resource declares `compatibleResources`

Depot fields

V2 field	In V3
`name`	`depots[].id`. The mapping generates its own ids
`cost`	`depots[].cost_per_visit`
`windows`	No depot opening hours
`capacity`	No equivalent

Option fields

V2 field	In V3
`routingEngine`	`problem.travel.engine`: `tomtom` or `osm`. Without it the engine is `tomtom`. `GOOGLE` and `ANYMAP` have no V3 value
`euclidian`	No equivalent
`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.polylines`
`partialPlanning`	Always on
`snapUnit`	No equivalent
`explanation`	Not needed: `unassigned[]` always carries reasons, and `evaluate` returns `violations[]`
`fairWorkloadPerTrip`, `fairWorkloadPerResource`, `fairComplexityPerTrip`, `fairComplexityPerResource`, `workloadSensitivity`	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` 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[].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	`skills[]`
Skill levels	No	Yes	`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	`locked_vehicle`
Job priority	Yes	Yes	`priority`
Optional jobs	Yes	Yes	`drop_fee`
Relations	Yes	Partial	`sequence`, `same_vehicle`, `same_day`, `same_route`, `synchronized`, `time_lag`, `compatible_vehicles`, `all_or_none`. `DIRECT_SEQUENCE` is approximated; `NEIGHBOR` has no equivalent; all-or-nothing only for jobs tied by `synchronized` or `time_lag`
Pickup and delivery	Yes	Yes	`shipments[]`
Maximum distance	Yes	Yes	`limits.max_distance_m`
Maximum drive time	Yes	Partial	`limits.max_leg_travel_time_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; `preferred_date` and `same_day` steer the day
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	No
Job proximity	Yes	Yes	`objective.grouping`
Route clustering	Yes	No
Custom distance matrix	Yes	No
Routing engine choice	Yes	Partial	`travel.engine`: `tomtom` or `osm`. No `GOOGLE` or `ANYMAP`
Vehicle profile	Yes	Yes	`vehicles[].profile`: `car`, `truck`, `bike`
Route polylines	Yes	Yes	`options.polylines`
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	`?validate_only=true`
Departure-time traffic	No	Yes	`travel.departure_time`
Per-vehicle costs	Yes	Yes	`vehicles[].costs` (and `shifts[].costs`): `fixed`, `per_route_hour`, `per_travel_km`, `per_wait_hour`, `per_overtime_hour`, each replacing the fleet value

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

​What a V2-shaped response contains

​V2 fields that are not carried over

​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

What a V2-shaped response contains

V2 fields that are not carried over

Top-level fields

Resource and shift fields

Job fields

Relation fields

Depot fields

Option fields

Feature parity