Quickstart - Solvice Docs

Overview

The V3 Routing API is a high-performance vehicle routing solver: send it jobs (and, for pickup-then-delivery work, shipments) plus a fleet of vehicles, and it returns optimised routes with arrival times, an itemised cost breakdown, and structured reasons for anything it couldn’t assign. It replaces the V2 VRP API (/v2/vrp/sync/solve, still available for backwards compatibility — see Migration from V2) with a faster engine, named capacity dimensions, and a money-denominated cost model everywhere.

Base URL

https://api.solvice.io/v3/routing

Five endpoints make up the API:

Method	Path	Purpose
`POST`	`/v3/routing/solve`	Optimise a full routing problem
`POST`	`/v3/routing/solve/stream`	Same request, streamed as Server-Sent Events (`progress`/`solution`/`done`)
`POST`	`/v3/routing/evaluate`	Score an existing set of routes without optimising
`POST`	`/v3/routing/suggest`	Rank insertion positions for new jobs into an existing plan
`POST`	`/v3/routing/validate`	Pre-matrix validation only — no matrix fetch, no solve

This guide covers /v3/routing/solve, the one you’ll use first.

Your first solve

Get your API key

Sign in to the Solvice Dashboard and copy your API key from Settings → API Keys. See Authentication for the full flow.

Send a solve request

curl -X POST https://api.solvice.io/v3/routing/solve \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vehicles": [
      {
        "id": "truck-1",
        "capacity": { "weight": 100 },
        "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] }
          }
        ]
      }
    ],
    "jobs": [
      {
        "id": "delivery-1",
        "location": { "coordinate": [4.7005, 50.8798] },
        "service_duration_s": 300,
        "time_windows": [
          {
            "from": "2026-04-01T09:00:00+02:00",
            "to":   "2026-04-01T12:00:00+02:00"
          }
        ],
        "demand": { "weight": 10 }
      },
      {
        "id": "delivery-2",
        "location": { "coordinate": [3.7303, 51.0500] },
        "service_duration_s": 600,
        "time_windows": [
          {
            "from": "2026-04-01T10:00:00+02:00",
            "to":   "2026-04-01T15:00:00+02:00"
          }
        ],
        "demand": { "weight": 20 }
      }
    ],
    "options": {
      "runtime": { "time_limit_s": 5 }
    }
  }'

Read the response

The response carries a summary, one entry per non-empty routes[], and any unassigned jobs with structured reasons:

{
  "summary": {
    "status": "solved",
    "vehicles_used": 1,
    "jobs_assigned": 2,
    "jobs_unassigned": 0,
    "total_distance_m": 142000,
    "total_duration_s": 14400,
    "estimated_cost": {
      "total": 168.4,
      "components": { "travel": 168.4, "waiting": 0.0 }
    },
    "elapsed_ms": 850,
    "iterations": 1200
  },
  "routes": [
    {
      "vehicle": "truck-1",
      "distance_m": 142000,
      "duration_s": 14400,
      "overtime_s": 0,
      "stops": [
        {
          "type": "start",
          "depot": "truck-1",
          "location": [4.3517, 50.8503],
          "arrival": "2026-04-01T08:00:00+02:00",
          "departure": "2026-04-01T08:00:00+02:00"
        },
        {
          "type": "job",
          "id": "delivery-2",
          "location": [3.7303, 51.0500],
          "arrival": "2026-04-01T10:00:00+02:00",
          "departure": "2026-04-01T10:10:00+02:00",
          "wait_s": 0,
          "service_s": 600,
          "travel_time_s": 7200,
          "load_after": { "weight": 20 }
        },
        {
          "type": "job",
          "id": "delivery-1",
          "location": [4.7005, 50.8798],
          "arrival": "2026-04-01T11:10:00+02:00",
          "departure": "2026-04-01T11:15:00+02:00",
          "wait_s": 0,
          "service_s": 300,
          "travel_time_s": 3600,
          "load_after": { "weight": 30 }
        },
        {
          "type": "end",
          "depot": "truck-1",
          "location": [4.3517, 50.8503],
          "arrival": "2026-04-01T12:15:00+02:00"
        }
      ]
    }
  ],
  "unassigned": []
}

routes[].vehicle is the plain vehicle.id string from the request — not a { "type", "instance" } object; there is no vehicle count/clone field in V3 (fleet size is one entry per physical vehicle). This request set no objective, so V3 seeded its default travel baseline (€0.20/km, €35/travel-hour) to compute the 168.4 above, and estimated_cost.currency is absent because no objective.costs.currency label was sent. travel and waiting are always present in components; drop_fees and overtime appear only when the request has a droppable task or per_overtime_hour set. See Objective Function for the full breakdown.

What’s new in V3

Feature	V2	V3
Solver engine	Timefold	Next-gen Solvice engine
Task model	`jobs[]` (flat V2 schema)	`jobs[]` (single-stop visits) + `shipments[]` (pickup→delivery pairs)
Capacity / demand	Array `[100]`	Named map `{ "weight": 100 }`
Start/end depot	Vehicle top-level	Inside `shifts[]`
Distance matrices	Manual or auto	Auto via Solvice Maps
Response format	Nested trips/visits	Typed `stops[]` with `load_after` named map
Cost breakdown	None	Itemised, currency-denominated `estimated_cost` in every response
Route identity in response	`resource` (name)	`vehicle` (plain id string)
Endpoint	`/v2/vrp/sync/solve`	`/v3/routing/solve`

Next steps

Migration from V2 — map V2 concepts to V3
The V3 API Model — jobs, shipments, vehicles, relations, objective
Constraints — every field-level constraint the solver enforces, hard vs. soft
API Reference — full endpoint documentation
Concepts — understand jobs, vehicles, constraints, and objectives

​Overview

​Base URL

​Your first solve

​What’s new in V3

​Next steps

Overview

Base URL

Your first solve

What’s new in V3

Next steps