Quickstart - Solvice Docs

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

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 endpoints make up the API:

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. Add ?validate_only=true to any of them to check a request 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 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 solve that should run longer than 300 seconds, or without holding a connection, can be submitted as an async run instead: 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": { "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": { "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": {
      "violations": 0,
      "unserved_priority": 0,
      "cost": 158.9642,
      "components": {"fixed": 0.0, "time": 121.5, "distance": 37.4642, "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": 187321,
    "time": {"span_s": 12500, "travel_s": 9655, "service_s": 900, "depot_s": 0, "wait_s": 1945, "break_s": 0, "overtime_s": 0},
    "timings": {"search_ms": 5012, "total_ms": 5149}
  },
  "routes": [
    {
      "vehicle": "truck-1",
      "shift": "mon",
      "distance_m": 187321,
      "time": {"span_s": 12500, "travel_s": 9655, "service_s": 900, "depot_s": 0, "wait_s": 1945, "break_s": 0, "overtime_s": 0},
      "load_peak": {"weight": 30},
      "stops": [
        {
          "type": "start",
          "location": [4.3517, 50.8503],
          "snapped_location": [4.35171, 50.85034],
          "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.70046, 50.87983],
          "arrival": "2026-04-01T08:27:35+02:00",
          "service_start": "2026-04-01T09:00:00+02:00",
          "departure": "2026-04-01T09:05:00+02:00",
          "wait_s": 1945,
          "service_s": 300,
          "travel_s": 1655,
          "distance_m": 32107,
          "lateness_s": 0,
          "load_after": {"weight": 20}
        },
        {
          "type": "job",
          "id": "delivery-2",
          "location": [3.7303, 51.05],
          "snapped_location": [3.73028, 51.05004],
          "arrival": "2026-04-01T10:23:46+02:00",
          "service_start": "2026-04-01T10:23:46+02:00",
          "departure": "2026-04-01T10:33:46+02:00",
          "wait_s": 0,
          "service_s": 600,
          "travel_s": 4726,
          "distance_m": 91687,
          "lateness_s": 0,
          "load_after": {"weight": 0}
        },
        {
          "type": "end",
          "location": [4.3517, 50.8503],
          "snapped_location": [4.35171, 50.85034],
          "arrival": "2026-04-01T11:28:20+02:00",
          "departure": "2026-04-01T11:28:20+02:00",
          "service_s": 0,
          "travel_s": 3274,
          "distance_m": 63527,
          "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,945 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, the moment its window opens, and the same as arrival at delivery-2.
Load. delivery 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 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: 187.321 km × 0.20 = 37.4642, and 12,500 s × 0.00972 = 121.5. 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.
Score. Every entry of score.components is always present. score.currency is absent here because no objective.currency label was sent.
Coverage. tasks.unserved is 0 because nothing is unassigned. If some jobs cannot be placed the call still returns 200, with tasks.unserved 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` is goods dropped off and `pickup` 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[]` (`{ code, 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