Quickstart - Solvice Docs

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

This page describes the V3 API (/v3/routing). For the V2 API (/v2/vrp), see the V2 version of this page.

The V3 Routing API is Solvice’s 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 is the successor to the V2 VRP API, with named capacity dimensions and money-denominated costs everywhere. If you are coming from V2, see Migration from V2. Three routing endpoints make up the core of the API (see the Introduction for validation and runs):

Method	Path	Purpose
`POST`	`/v3/routing/solve`	Optimise a full routing problem
`POST`	`/v3/routing/evaluate`	Score an existing set of routes without optimising. See Evaluate
`POST`	`/v3/routing/suggest`	Rank insertion positions for new jobs into an existing plan. See Suggest

All three are served from https://api.solvice.io and take a JSON body with your API key in the Authorization header. Send a request to POST /v3/routing/validate/solve, /v3/routing/validate/evaluate or /v3/routing/validate/suggest to check it without solving it: it runs every check the real call runs before its travel-matrix fetch, then returns 200 {"valid": true, "warnings": []} or the same 400 (or 403) the real call would return. No matrix fetch, no search, not billed. Request bodies may be gzip-compressed (Content-Encoding: gzip); the 10 MiB limit applies after decompression. See Limits for the other caps. A problem of 401 to 10,000 tasks must be submitted as an async run, and a solve that should run longer than 60 seconds, or without holding a connection, can be: POST /v3/routing/runs takes the same body. This guide covers /v3/routing/solve, the one you’ll use first.

Your first solve

Get your API key

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 '{
    "problem": {
      "jobs": [
        {
          "id": "delivery-1",
          "location": [4.7005, 50.8798],
          "service_duration_s": 300,
          "time_windows": [
            { "from": "2026-04-01T09:00:00+02:00", "to": "2026-04-01T12:00:00+02:00" }
          ],
          "delivery_load": { "weight": 10 }
        },
        {
          "id": "delivery-2",
          "location": [3.7303, 51.0500],
          "service_duration_s": 600,
          "time_windows": [
            { "from": "2026-04-01T10:00:00+02:00", "to": "2026-04-01T15:00:00+02:00" }
          ],
          "delivery_load": { "weight": 20 }
        }
      ],
      "vehicles": [
        {
          "id": "truck-1",
          "capacity": { "weight": 100 },
          "shifts": [
            {
              "id": "mon",
              "from": "2026-04-01T08:00:00+02:00",
              "to":   "2026-04-01T17:00:00+02:00",
              "start": { "location": [4.3517, 50.8503] },
              "end":   { "location": [4.3517, 50.8503] }
            }
          ]
        }
      ]
    },
    "options": {
      "time_limit_s": 5
    }
  }'

Read the response

The response carries a summary, one entry per non-empty routes[], the same routes as a plan, and any unassigned jobs with structured reasons. Stop times are instants in the shift’s own UTC offset (+02:00 here); distances and durations come from the road network. The figures below are illustrative: a live solve returns the road-network values for your coordinates.

{
  "summary": {
    "score": {
      "violation_count": 0,
      "unassigned_priority": 0,
      "cost": 134.97264,
      "components": {"routes": 0.0, "vehicles": 0.0, "time": 101.05884, "distance": 33.9138, "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": 169569,
    "time": {"span_s": 10397, "travel_s": 7762, "service_s": 900, "depot_s": 0, "wait_s": 1735, "break_s": 0, "overtime_s": 0},
    "timings": {"search_ms": 500, "total_ms": 736},
    "search": {"termination": "time_limit", "iterations": 304603}
  },
  "routes": [
    {
      "vehicle": "truck-1",
      "shift": "mon",
      "distance_m": 169569,
      "time": {"span_s": 10397, "travel_s": 7762, "service_s": 900, "depot_s": 0, "wait_s": 1735, "break_s": 0, "overtime_s": 0},
      "load_peak": {"weight": 30},
      "stops": [
        {
          "type": "start",
          "location": [4.3517, 50.8503],
          "snapped_location": [4.351767, 50.850338],
          "arrival": "2026-04-01T08:00:00+02:00",
          "departure": "2026-04-01T08:00:00+02:00",
          "service_s": 0,
          "load_after": {"weight": 30}
        },
        {
          "type": "job",
          "id": "delivery-1",
          "location": [4.7005, 50.8798],
          "snapped_location": [4.700512, 50.879795],
          "arrival": "2026-04-01T08:32:43+02:00",
          "service_start": "2026-04-01T09:00:00+02:00",
          "departure": "2026-04-01T09:05:00+02:00",
          "wait_s": 1637,
          "service_s": 300,
          "travel_s": 1963,
          "distance_m": 30444,
          "lateness_s": 0,
          "load_after": {"weight": 20}
        },
        {
          "type": "job",
          "id": "delivery-2",
          "location": [3.7303, 51.05],
          "snapped_location": [3.730347, 51.050016],
          "arrival": "2026-04-01T09:58:22+02:00",
          "service_start": "2026-04-01T10:00:00+02:00",
          "departure": "2026-04-01T10:10:00+02:00",
          "wait_s": 98,
          "service_s": 600,
          "travel_s": 3202,
          "distance_m": 83696,
          "lateness_s": 0,
          "load_after": {"weight": 0}
        },
        {
          "type": "end",
          "location": [4.3517, 50.8503],
          "snapped_location": [4.351767, 50.850338],
          "arrival": "2026-04-01T10:53:17+02:00",
          "departure": "2026-04-01T10:53:17+02:00",
          "wait_s": 0,
          "service_s": 0,
          "travel_s": 2597,
          "distance_m": 55429,
          "load_after": {"weight": 0}
        }
      ]
    }
  ],
  "plan": {
    "routes": [
      {
        "vehicle": "truck-1",
        "shift": "mon",
        "stops": [
          {"type": "job", "id": "delivery-1"},
          {"type": "job", "id": "delivery-2"}
        ]
      }
    ]
  },
  "unassigned": []
}

How to read it:

Identity. routes[].vehicle and routes[].shift are the plain id strings from the request.
Stops. Each stop’s location is the coordinate you sent; snapped_location is the same point snapped to the road network, when available. arrival is before any waiting: the 1,637 s of wait_s at delivery-1 is the truck arriving before that job’s window opens. service_start is when service begins, after the wait: 09:00 at delivery-1 and 10:00 at delivery-2, the moments their windows open.
Load. delivery_load on a job is goods loaded at the depot and dropped off at the job, so load_after starts at 30 on the start stop and falls to 0. Use pickup_load on a job for goods that go onto the vehicle there, which makes load_after rise instead. See Jobs.
Durations. time.travel_s is driving time only. time.span_s is the route’s span from its start to its finish, including service and waiting.
Cost. This request set no objective, so the default rates apply: 0.20 per km of distance_m and 35 per hour of time.span_s. That gives the distance and time components above: 169.569 km × 0.20 = 33.9138, and 10,397 s × 0.00972 = 101.05884. They sum to score.cost. The hourly rate is applied per second at a resolution of 5 decimals, so 35 per hour is charged as 0.00972 per second. Expect the time component to come out a few cents under hours × 35.
Search time. timings.search_ms is 500 although time_limit_s is 5: a solve without a plan for one vehicle with one shift and time windows on its jobs caps its search at 500 ms below 60 visits, when time_limit_s is 6 or less. See Performance.
Score. Every entry of score.components is always present. score.currency is absent here because no objective.currency label was sent.
Coverage. tasks.unassigned is 0 because nothing is unassigned. If some jobs cannot be placed the call still returns 200, with tasks.unassigned above 0 and one unassigned[] entry per job explaining why.
Plan. plan carries the same routes in the request’s plan vocabulary. Feed it straight into evaluate, suggest, or a warm-started solve.

See The V3 API model for every response field, Objective function for the cost breakdown, and Solution quality for how to judge a plan.

Got a 400 instead? The body names the offending field in errors[].pointer. See Errors.

What’s different from V2

Aspect	V2 (`/v2/vrp/sync/solve`)	V3 (`/v3/routing/solve`)
Task model	`jobs[]` (flat V2 schema)	`jobs[]` (single-stop visits) + `shipments[]` (pickup→delivery pairs)
Capacity and load	Array `[100]`	Named map `{ "weight": 100 }`. On a job, `delivery_load` is goods dropped off and `pickup_load` is goods collected
Coordinates	`{ "latitude": .., "longitude": .. }`	`[lon, lat]` (GeoJSON order)
Field naming	camelCase	snake_case
Timestamps	Often sent without a UTC offset	Include a UTC offset (`+02:00` or `Z`). A timestamp without one is a `400`
Vehicle	`resources[]`	`vehicles[]`
Vehicle start / end	`start`/`end` on the resource or its shifts	`start`/`end` in each `shifts[]` entry: `{ "location": ... }` or `{ "depot": "<depots[].id>" }`
Cost model	Weighted score, no currency	Itemised, currency-denominated `score` in every response
Route identity in response	`resource` (name)	`vehicle` (plain id string)
Unassigned reasons	`unservedReasons` (strings per job)	`unassigned[]` entries with a `category` and structured `reasons[]` (`{ constraint, message }`)

Next steps

The V3 API model

How the full request and response are structured: jobs, shipments, vehicles, relations, objective.

Field service day

A worked example: one day of service jobs solved, then a manual change scored with evaluate and a new job placed with suggest.

Constraints

Every field-level constraint the solver enforces, hard vs. soft.

Evaluate

Score an existing plan and list the rules it breaks.

Suggest

Rank where a new job fits into an existing plan.

Errors

The error body, every error code, and what to retry.

Limits

Request size, count, and time-limit caps.

Migration from V2

Map V2 concepts and fields onto V3.

API reference

Base URL, authentication, and the full schema of every endpoint.

​Your first solve

​What’s different from V2

​Next steps

The V3 API model

Field service day

Constraints

Evaluate

Suggest

Errors

Limits

Migration from V2

API reference

Your first solve

What’s different from V2

Next steps