Migration from V2 - Solvice Docs

Overview

The V3 Routing API is a ground-up rewrite with a new, faster solver engine replacing Timefold. The V2 endpoint (/v2/vrp/sync/solve) remains available for backwards compatibility — internally it maps to V3 and back.

Endpoint change

	V2 (OnRoute)	V3 (Routing)
URL	`POST /v2/vrp/sync/solve`	`POST /v3/routing/solve`
Auth	`Authorization: API_KEY`	`Authorization: API_KEY`
Coordinate format	`{"latitude": 50.85, "longitude": 4.35}`	`{ "coordinate": [4.35, 50.85] }` (GeoJSON: lon, lat)
Time format	ISO 8601 strings	ISO 8601 strings
Field naming	camelCase	snake_case

Request mapping

Vehicles (Resources → Vehicles)

{
  "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": ["refrigerated"],
  "shifts": [
    {
      "from": "2026-04-01T08:00:00+02:00",
      "to": "2026-04-01T17:00:00+02:00",
      "start": { "coordinate": [4.3517, 50.8503] },
      "end":   { "coordinate": [4.3517, 50.8503] }
    }
  ]
}

Key differences:

name → id
shifts[].start/end move to inside shifts[] as a Place ({ "coordinate": [lon, lat] }) — this is still inside the shift in both V2 and V3, but the coordinate format changes
Coordinates: { "latitude", "longitude" } object → { "coordinate": [longitude, latitude] } Place (GeoJSON order, wrapped in object)
capacity: array [100] → named map { "weight": 100 } (dimension names must match job demand keys)
tags → skills (resource-level tags[] is mapped 1:1 via the V2 compat endpoint; only per-shift shifts[].tags — per-shift capability tags — has no V3 equivalent, since V3 skills are vehicle-level, not shift-level)
New: limits.max_distance_m, limits.max_route_duration_s for vehicle range constraints (max_route_duration_s caps the whole route span — travel + service + wait — not pure drive time; V3 has no pure-drive-time cap)

Jobs

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

{
  "id": "delivery-1",
  "location": { "coordinate": [4.7005, 50.8798] },
  "service_duration_s": 300,
  "demand": { "weight": 10 },
  "time_windows": [
    {
      "from": "2026-04-01T09:00:00+02:00",
      "to": "2026-04-01T12:00:00+02:00"
    }
  ]
}

Key differences:

name → id
location: { "latitude", "longitude" } → Place object { "coordinate": [longitude, latitude] }
duration → service_duration_s (still in seconds)
load array → demand named map (e.g. [10] → { "weight": 10 })
windows → time_windows (no hard flag — all time windows are hard in V3 Phase 1)
Skills: skills: [{ "name": "refrigerated" }] — supported today; all required skills must be present on the vehicle
Committed vehicle: a hard pin uses locked_vehicle (survives re-optimization). eligible_vehicles: { "allowed": [...] } is a different mechanism — an eligibility whitelist among several allowed vehicles, not a single-vehicle pin

Relations

V3 uses a tagged-union format with job_ids (not jobs). V2 relation types map as follows:

V2 `type`	V3 `type`	Notes
`SEQUENCE`	`ordered`	`job_ids` instead of `jobs`; `relations[].resource` pin → `locked_vehicle` applied to every member of the relation

V2 has no dedicated “pin job first” relation type. To pin a job to the first position in a route, submit a SEQUENCE relation with a single job id in jobs — the V2 solver derives first-job placement from that single-entry sequence internally. The V3 equivalent is the same pattern: an ordered relation with a single entry in job_ids.

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

{
  "type": "ordered",
  "job_ids": ["job-A", "job-B", "job-C"]
}

Note: V2’s resource field (pin relation to a specific vehicle) maps to locked_vehicle applied to every job in the relation — supported today, not a workaround.

Options

POST /v2/vrp/solve?millis=5000

{
  "options": {
    "runtime": {
      "time_limit_ms": 5000,
      "seed": 42
    }
  }
}

Key differences:

V2’s ?millis= query parameter (already in milliseconds) → options.runtime.time_limit_ms request body field (also milliseconds)
New: options.runtime.seed for reproducible results
New: options.runtime.matrix — supply custom distance/duration matrices (bypasses Solvice Maps)
Objective tuning (minimize time vs. distance) is configured via the objective field — Coming soon

Response mapping

{
  "trips": [
    {
      "resource": "truck-1",
      "visits": [
        {
          "job": "delivery-1",
          "arrival": "2026-04-01T09:30:00+02:00",
          "location": { "latitude": 50.8798, "longitude": 4.7005 }
        }
      ],
      "travelTime": 3600,
      "distance": 30000
    }
  ],
  "unserved": ["delivery-3"],
  "unservedReasons": {
    "delivery-3": ["Time window violated"]
  },
  "totalTravelTimeInSeconds": 3600,
  "totalTravelDistanceInMeters": 30000
}

{
  "summary": {
    "status": "solved",
    "total_distance_m": 142000,
    "total_duration_s": 7200,
    "vehicles_used": 1,
    "jobs_assigned": 2,
    "jobs_unassigned": 0,
    "estimated_cost": {
      "total": 7200,
      "components": {
        "travel": 7200,
        "waiting": 0,
        "overtime": 0,
        "lateness": 0,
        "vehicles_fixed": 0,
        "unassigned": 0,
        "preferences": 0,
        "imbalance": 0
      }
    },
    "elapsed_ms": 850,
    "iterations": 1200
  },
  "routes": [
    {
      "vehicle": "truck-1",
      "distance_m": 142000,
      "duration_s": 7200,
      "overtime_s": 0,
      "stops": [
        {
          "type": "start",
          "location": [4.3517, 50.8503],
          "departure": "2026-04-01T08:00:00+02:00"
        },
        {
          "type": "job",
          "id": "delivery-2",
          "location": [3.7303, 51.0500],
          "arrival": "2026-04-01T08:40:00+02:00",
          "departure": "2026-04-01T08:50:00+02:00",
          "wait_s": 0,
          "service_s": 600,
          "travel_time_s": 2400,
          "load_after": { "weight": 20 }
        },
        {
          "type": "job",
          "id": "delivery-1",
          "location": [4.7005, 50.8798],
          "arrival": "2026-04-01T09:50:00+02:00",
          "departure": "2026-04-01T09:55:00+02:00",
          "wait_s": 0,
          "service_s": 300,
          "travel_time_s": 3600,
          "load_after": { "weight": 30 }
        },
        {
          "type": "end",
          "location": [4.3517, 50.8503],
          "arrival": "2026-04-01T10:30:00+02:00"
        }
      ]
    }
  ],
  "unassigned": []
}

Key differences:

trips → routes; resource → vehicle (a plain vehicle-id string, e.g. "truck-1")
visits → stops (typed: start, job, end, etc.)
V3 stops carry type, id, arrival, departure, wait_s, service_s, travel_time_s, load_after (named map)
V3 routes use distance_m / duration_s (not bare distance / duration)
unserved (string list) → unassigned (objects with job_id and reasons[])
New summary block with jobs_assigned/jobs_unassigned, total_distance_m, total_duration_s, estimated_cost, elapsed_ms, iterations
Coordinates in response are bare [longitude, latitude] arrays

V2 features not mapped via compat endpoint

When using the V2 endpoint (/v2/vrp/sync/solve), the following V2 fields are silently dropped during conversion:

shifts[].tags (per-shift capability tags) — V3 skills are vehicle-level; split the resource into one V3 vehicle per differing shift to approximate this. (Resource-level resources[].tags itself is forwarded, via skills.)
windows[].hard: false + its per-window weight — V3 can price lateness fleet-wide via objective.costs.per_late_hour, but the per-window weight is lost; there is no per-window soft-cost equivalent
Per-visit serviceTime, travelTime, distance — not populated in the V2 response

Feature parity

Most of V2’s features already ship in V3 today, often via a different mechanism (currency-priced rather than ranked, or a coarser-grained workaround field). A handful remain genuine gaps.

Feature	V2	V3	Notes
Capacity (single dimension)	✅	✅	Named map e.g. `{ "weight": 100 }`
Multi-dimensional capacity	✅	✅	Up to 4 named dimensions; names must match job `demand` keys
Time windows (hard)	✅	✅
Multiple time windows per job	✅	✅	`time_windows[]` supports more than one window; each hard on both sides
Soft time windows	✅	🔜	V3 only prices lateness fleet-wide (`objective.costs.per_late_hour`); a true per-window soft weight has no equivalent yet
Skills / tags	✅	✅
Skill levels / proficiency	✅	🛠	`vehicles[].service_factor` — per vehicle for all jobs, not per (job, vehicle) pair
Sequence / precedence	✅	✅	V2: `SEQUENCE` relation (single job id pins it first); V3 type: `ordered` with `job_ids`
Job relations (same route, same time, etc.)	✅	✅	`same_resource`, `synchronized`, `ordered` cover most cases; `same_day` is native-only (400 via the V2 compat path); `NEIGHBOR` has no V3 equivalent
Tag ranking	✅	🛠	`preferences[]`, one entry per ranked vehicle — give the best rank the largest `violation_cost`
Job priority	✅	🛠	`mandatory: false` + `drop_fee` — priced in currency, not ranked; a task without a fee is must-serve
Vehicle range (max distance / route duration)	✅	✅	`limits.max_distance_m`, `limits.max_route_duration_s` (route span — travel + service + wait — not pure drive time)
Committed vehicle	✅	✅	Hard pin: `locked_vehicle`. `eligible_vehicles.allowed` is a separate eligibility whitelist, not a pin
Driver breaks	✅	✅	Windowed, drive-time-triggered, duty-time-triggered, and fixed-unavailability breaks all supported
Pickup & delivery (shipments)	✅	✅	`shipments[]` (pickup/delivery pair); compat auto-detects eligible V2 relation pairs
Custom distance matrix	✅	✅	`options.runtime.matrix`
Auto distance matrix (Solvice Maps)	✅	✅
Multi-day planning	✅	✅	Multi-shift vehicles (`shift_index`/`parent_vehicle`/`day`) plus `preferred_date` support week-horizon planning
Inherited location	✅	🔜	Coming soon
Workload balancing / fairness	✅	🔜	Core term exists internally but is unreachable from any endpoint today
Rules engine (periodic caps)	✅	🔜	Design proposed (`limits.periods[]`); day-1 approximation is a per-day `max_route_duration_s` on a one-shift-per-day resource
Real-time re-optimization	—	🔜	Coming soon
SSE streaming progress	—	✅	New in V3
Job proximity constraint	—	✅	New in V3

V3 is under active development. The V2 endpoint (/v2/vrp/sync/solve) remains available and internally maps to the V3 solver — you get V3’s performance with the V2 API contract.

​Overview

​Endpoint change

​Request mapping

​Vehicles (Resources → Vehicles)

​Jobs

​Relations

​Options

​Response mapping

​V2 features not mapped via compat endpoint

​Feature parity

Overview

Endpoint change

Request mapping

Vehicles (Resources → Vehicles)

Jobs

Relations

Options

Response mapping

V2 features not mapped via compat endpoint

Feature parity