Evaluate

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

Overview

POST /v3/routing/evaluate takes a problem and a plan and tells you what that plan is worth. It computes arrival times, loads and the cost breakdown exactly as a solve would, and lists every hard constraint the plan breaks. It never moves a stop. Typical uses:

Check a plan a dispatcher edited by hand before you commit it.
Compare your current planning against a solve result on the same cost model.
Get the full timeline after you apply a suggestion.
Re-score yesterday’s plan against today’s constraints.

The request

object

required

The same problem object as on /v3/routing/solve. See the V3 API model.

object

required

The plan to score: routes[], one entry per vehicle shift that serves something.

Evaluate takes no options: there is no search, so there is nothing to tune. An options key is rejected as an unknown field.

The plan shape

The value of plan:

{
  "routes": [
    {
      "vehicle": "truck-1",
      "shift": "mon",
      "stops": [
        { "type": "job", "id": "delivery-2" },
        { "type": "job", "id": "delivery-1" }
      ]
    }
  ]
}

Field	Meaning
`routes[].vehicle`	A `vehicles[].id` from the problem
`routes[].shift`	The id of one of that vehicle’s `shifts[]`. Each vehicle shift may appear once
`routes[].stops[]`	The task stops in visiting order
`routes[].stops[].pinned`	Optional, on `job`, `pickup` and `delivery` stops. Accepted and ignored by evaluate: the plan is scored as listed. On solve it keeps the stop on its vehicle
`routes[].locked_count`	Optional. Used by solve and suggest; evaluate only checks that it does not exceed the number of stops and is not combined with a `reload` stop

A stop is one of:

Stop	Meaning
`{ "type": "job", "id": "..." }`	A job, by its id
`{ "type": "pickup", "id": "..." }`	A shipment’s pickup. The id is the pickup’s own `id` if you gave it one, otherwise `<shipment id>:pickup`
`{ "type": "delivery", "id": "..." }`	A shipment’s delivery, named the same way with `:delivery`. It must come after its pickup on the same route
`{ "type": "reload", "depot": "..." }`	A mid-route return to a depot listed in that shift’s `reloads`. It starts a new trip and must sit between two task stops; on a shift with a non-zero `initial_load` it may also come first, as the unload before the first job. One route can reload at the same depot at most 8 times

Start, end and break stops are not listed; they are placed for you. Every solve and evaluate response returns its routes in this shape as plan, so a result’s plan can be sent back unchanged. A task you leave out of every route is not an error. It is reported in unassigned[], with a category that says whether it could be added: see What unassigned means on evaluate.

Example

The quickstart’s two deliveries, with delivery-1 due by 11:00 local time and a hand-made plan that visits delivery-2 first:

curl -X POST https://api.solvice.io/v3/routing/evaluate \
  -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-01T11: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] }
            }
          ]
        }
      ]
    },
    "plan": {
      "routes": [
        {
          "vehicle": "truck-1",
          "shift": "mon",
          "stops": [
            { "type": "job", "id": "delivery-2" },
            { "type": "job", "id": "delivery-1" }
          ]
        }
      ]
    }
  }'

The response

The response has the same four parts as a solve response: summary, routes, plan and unassigned. The figures below are illustrative; yours depend on live travel times.

{
  "summary": {
    "score": {
      "violation_count": 1,
      "unassigned_priority": 0,
      "cost": 178.76944,
      "components": {"routes": 0.0, "vehicles": 0.0, "time": 141.25104, "distance": 37.5184, "waiting": 0.0, "driving": 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": 187592,
    "time": {"span_s": 14532, "travel_s": 9733, "service_s": 900, "depot_s": 0, "wait_s": 3899, "break_s": 0, "overtime_s": 0},
    "timings": {"total_ms": 121},
    "search": {"termination": "not_searched", "iterations": 0}
  },
  "routes": [
    {
      "vehicle": "truck-1",
      "shift": "mon",
      "distance_m": 187592,
      "time": {"span_s": 14532, "travel_s": 9733, "service_s": 900, "depot_s": 0, "wait_s": 3899, "break_s": 0, "overtime_s": 0},
      "load_peak": {"weight": 30},
      "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,
          "load_after": {"weight": 30}
        },
        {
          "type": "job",
          "id": "delivery-2",
          "location": [3.7303, 51.05],
          "arrival": "2026-04-01T08:55:01+02:00",
          "service_start": "2026-04-01T10:00:00+02:00",
          "departure": "2026-04-01T10:10:00+02:00",
          "wait_s": 3899,
          "service_s": 600,
          "travel_s": 3301,
          "distance_m": 63610,
          "lateness_s": 0,
          "load_after": {"weight": 10}
        },
        {
          "type": "job",
          "id": "delivery-1",
          "location": [4.7005, 50.8798],
          "arrival": "2026-04-01T11:29:20+02:00",
          "service_start": "2026-04-01T11:29:20+02:00",
          "departure": "2026-04-01T11:34:20+02:00",
          "wait_s": 0,
          "service_s": 300,
          "travel_s": 4760,
          "distance_m": 91802,
          "lateness_s": 1760,
          "load_after": {"weight": 0},
          "violations": [
            {"code": "time_window", "message": "Arrives 1760s after latest allowed time", "excess": 1760, "unit": "s"}
          ]
        },
        {
          "type": "end",
          "location": [4.3517, 50.8503],
          "arrival": "2026-04-01T12:02:12+02:00",
          "departure": "2026-04-01T12:02:12+02:00",
          "wait_s": 0,
          "service_s": 0,
          "travel_s": 1672,
          "distance_m": 32180,
          "load_after": {"weight": 0}
        }
      ]
    }
  ],
  "plan": {
    "routes": [
      {
        "vehicle": "truck-1",
        "shift": "mon",
        "stops": [
          {"type": "job", "id": "delivery-2"},
          {"type": "job", "id": "delivery-1"}
        ]
      }
    ]
  },
  "unassigned": []
}

The truck reaches delivery-1 at 11:29:20 local time (+02:00, the shift’s offset), 1,760 seconds after its window closed at 11:00:00. The plan is still scored in full, so you can see what it would cost and how late it would be.

How it differs from a solve response

Field	On evaluate
`summary.score.violation_count`	The number of hard constraints the plan breaks, across all routes and stops; `0` when it breaks none. It says nothing about tasks left out of the plan. On a solve response it is `0` unless a `pinned` stop forces a relation breach, counted the same way
`routes[].stops[].violations`	Violations found at that stop. Absent when there are none
`routes[].violations`	Violations that belong to the route as a whole. Absent when there are none
`summary.timings.search_ms`	Not present: nothing is searched
`unassigned[]`	Every task of `problem` that is in no route of your plan, in the same shape as on solve. The categories read differently: see below

Everything else, including the stop timeline and score.components, reads exactly as on solve. See the Quickstart for the stop fields and Objective function for the cost breakdown. In a request that contains shipments, summary.tasks.served and summary.tasks.unassigned count a shipment once, like a job, whether its two stops are in the plan or not; unassigned[] has one entry per job or shipment the plan leaves out, so its length equals summary.tasks.unassigned.

What unassigned means on evaluate

Evaluate never adds a task to your plan. For each task the plan leaves out, unassigned[].category tells you whether it could be added to the plan as it stands:

`category`	On evaluate
`impossible`	No vehicle can serve the task at all, or one of its `all_or_none` partners
`blocked`	Some vehicle could serve it alone, but it does not fit into the plan you sent, or one of its `all_or_none` partners does not, or its all-or-none crew cannot be placed together
`priced_out`	It fits, it has a `drop_cost`, and serving it at the cheapest position costs at least the fee
`time_limit`	It fits. It is unassigned only because your plan does not include it

A task that fits has one reason and no constraint: no constraint refused it, unless its all_or_none group holds it back (all_or_none) or its all-or-none crew cannot be placed together (synchronized, time_lag). To place such a task, add it to plan or ask /v3/routing/suggest for its best position. The constraint vocabulary is listed in Errors.

Violations

Each violation is { "code", "message" }, plus how far over the limit it is where that is one number. code is a stable string to branch on; message is for people. Unassigned reasons[].constraint uses the same values.

Field	Present	Meaning
`excess`	on `capacity`, `time_window`, `shift_end`, `max_distance`, `max_route_duration` and `quota`	How far over the limit, in `unit`
`unit`	with `excess`	`s` (seconds late or over), `m` (metres), `load` (load units) or `stops`
`dimension`	on `capacity`	The capacity dimension over its limit, e.g. `weight`

{"code": "capacity", "message": "Cumulative load 30 exceeds vehicle capacity 15 (dimension 0)", "dimension": "weight", "excess": 15, "unit": "load"}

`code`	Reported on	The plan breaks
`time_window`	stop	The task’s time window: service would start after it closes, measured from the arrival plus any `windowed` break taken on it
`capacity`	stop or route	The vehicle’s `capacity` in some dimension
`required_skills`	stop	The task’s `required_skills`
`serves_tags`	stop	The shift’s `serves_tags`
`eligible_vehicles`	stop	The task’s `eligible_vehicles`
`unreachable`	stop or route	There is no road connection for a leg of the route
`max_leg_travel`	stop or route	A leg of the route takes longer than the vehicle’s `limits.max_leg_travel_s`
`sequence`	stop	A `sequence` relation; one that lists a single job pins it as the first stop of its route
`tag_order`	stop	The `tag_order` relation
`shipment`	stop	Pickup and delivery pairing
`same_vehicle`	stop	A `same_vehicle` relation
`same_day`	stop	A `same_day` relation
`same_route`	stop	A `same_route` relation
`synchronized`	stop	A `synchronized` relation
`time_lag`	stop	A `time_lag` relation
`all_or_none`	stop	An `all_or_none` relation: some members are served and others are not. Every served member reports it
`compatible_vehicles`	stop	A `compatible_vehicles` relation: the group is served by two vehicles that are not compatible under `vehicles[].compatible_with`. Both sides of the split report it
`shift_end`	route	The route finishes after the shift’s end plus allowed overtime
`max_distance`	route	`limits.max_distance_m`
`max_route_duration`	route	`limits.max_route_duration_s`
`max_stops`	route	`limits.max_stops`
`break`	route	A break in `shifts[].breaks` cannot be taken as required
`multi_trip`	route	The shift’s reload rules
`period_limit`	route	A `limits.periods[]` cap. Reported once per period, on the route of the first shift used in it
`quota`	route	A `quotas[]` cap. Reported once per quota window, the same way
`unknown`	stop	A stop the solver would refuse, with no more specific code. Not expected in practice

New codes can be added as new constraints ship. Handle the ones you care about and treat anything else as a generic violation.

A time window priced as soft, through time_windows[].per_late_hour or objective.per_late_hour, is not a violation when it is missed. The lateness shows up in the stop’s lateness_s and in score.components.lateness instead.

What evaluate checks, and when

Evaluate needs real travel times to compute a timeline, so it fetches them the same way solve does. What it skips is the search.

The request is validated. Schema, references and limits are checked first. A problem here is a 400 and no travel times are fetched.
Travel times are fetched. If they cannot be, the plan is scored on estimated travel times and summary.travel_estimated is true; evaluate has no option to fail instead. The timeline, the violations and the score then hold only against the estimate, which can be tens of percent off: evaluate again once travel times can be fetched if the verdict must hold on the road. Coordinates that span more than one region are a 400. See Distance matrices.

The plan is matched to the problem. A plan that cannot be laid out at all is a 400 with one item, whose pointer is /plan/routes/{i} or /plan/routes/{i}/stops/{k}. The first such problem is reported:

The plan has	Item code
An unknown vehicle and shift pair, an unknown stop id, or a `reload` depot that is not in that shift’s `reloads`	`unknown_reference`
A route or a stop listed twice	`duplicate_id`
A `locked_count` larger than the number of stops, or more trips than `max_trips`	`out_of_range`
A `locked_count` on a route with a `reload` stop	`conflicting_fields`
A stop whose `type` does not match the task; a shipment whose pickup and delivery are not both on one route, pickup first; a `reload` that is first (on a shift without a non-zero `initial_load`), last or next to another `reload`; more than 8 reloads at one depot	`invalid_value`

The plan is scored. Everything else, such as a missed window or an overloaded vehicle, is reported as a violation in a 200 response.

Validate without scoring

POST /v3/routing/validate/evaluate runs step 1 only and returns 200 {"valid": true, "warnings": []} or the 400 the real call would return. It checks problem; it does not look at plan, because matching the plan needs the later steps.

Errors

Evaluate returns the same error body and status codes as solve, except 502 and 503: travel times it cannot fetch are estimated, and it never waits for a free solver. A plan with violations is not an error: it is a 200 with summary.score.violation_count above 0.

Suggest

Find the best slot for a new task in a plan you keep.

Errors

The error body, every code, and what to do about each.

Constraints

The rules behind each violation code.

API reference

Request and response schema for every endpoint.

Platform

Routing API

Overview

The request

The plan shape

Example

The response

How it differs from a solve response

What unassigned means on evaluate

Violations

What evaluate checks, and when

Validate without scoring

Errors

Suggest

Errors

Constraints

API reference