V3 is in beta. General availability (GA) is planned for January 2027.
| Term | Meaning | In the API | Read more |
|---|---|---|---|
| Problem | The routing input: tasks, fleet, depots, rules, prices and travel data. Nested under one key in every request body; vehicles and at least one job or shipment are required. | problem | A request at a glance |
| Plan, warm start | Which vehicle shift serves which stops, in order. Returned by every solve, required by evaluate and suggest. Sent with a solve request it seeds the search instead of starting from scratch; locked_count freezes a route’s dispatched prefix. | plan, plan.routes[].locked_count | Warm-starting with plan |
| Task, job | A task is a job or a shipment. A job is one visit at one location, with its own loads, skills, time windows and prices on the object. A job without location takes service time but no travel. | jobs[] | Jobs |
| Shipment | A pickup and a delivery served by one vehicle, pickup first, carrying load between the two legs. Counts as one task in summary.tasks and in unassigned[]. | shipments[], pickup, delivery | Shipments |
| Vehicle, shift | A vehicle holds capacity, skills, limits and a cost model. Each of its shifts is one working window (from to to) with a start and an end place, given inline as a location or by depot id. Each shift that serves a task becomes one route, so one vehicle with five shifts yields up to five routes. | vehicles[], shifts[], shifts[].start, shifts[].end | Vehicles and shifts |
| Depot | A named place a shift can start from, end at, or reload at, referenced by id. Carries a handling time per visit and a price per reload. | depots[], depots[].service_duration_s, depots[].per_reload | Depots |
| Reload, multi-trip | A mid-shift return to a depot that empties or restocks the vehicle and opens a new trip. Capacity holds per trip. Each reload is a stop of type reload in the response. | shifts[].reloads, shifts[].max_trips | Multi-trip reloads |
| Time window, service duration | A window bounds the start of service at a task; arriving early waits. Windows are hard unless a per_late_hour rate prices lateness instead. Service duration is the time spent at the stop once service starts. | time_windows[], time_windows[].per_late_hour, objective.per_late_hour, service_duration_s | Time windows |
| Skill | A capability a task requires and a vehicle provides, or a shift when shifts[].skills replaces the vehicle’s for that shift, matched by name, with an optional level. Hard: the serving shift’s effective skills must include every skill the task lists. | required_skills, vehicles[].skills, shifts[].skills | Skills |
| Tag | A zone or territory label on a task. A shift that lists serves_tags serves only tasks that share one of them (hard); a vehicle’s preferred_tags prices serving a task outside them (soft). | tags, shifts[].serves_tags, vehicles[].preferred_tags | Tags, serves_tags, and preferred_tags |
| Capacity, load | Named dimensions such as weight or volume, at most four per request. A job adds pickup_load to the vehicle or takes delivery_load off it; a shipment carries load. The running load never exceeds the vehicle’s capacity in any dimension. | capacity, pickup_load, delivery_load, load | Capacity |
| Relation | A hard rule between tasks, as a tagged object: order (sequence, consecutive, tag_order), grouping (same_vehicle, same_day, same_route, compatible_vehicles, all_or_none) or timing (synchronized, time_lag). | relations[], relations[].type | Relations |
| Quota, period limit | A quota caps how many of the listed tasks the listed vehicles serve together in a window. A period limit caps one vehicle’s totals across all its shifts per day, per week or in an explicit window. | quotas[], limits.periods[] | Quotas |
| Priority, optional task, drop cost | Every task is must-serve unless it carries a drop_cost, the fee for leaving it out. Among must-serve tasks, priority ranks which are kept when not all fit. | priority, drop_cost | Priority and optional tasks |
| Objective, costs, score | Every soft rule is money in your currency. Rates on the fleet, a vehicle or a shift price travel, time, waiting, overtime and vehicle use. The response scores a plan by violation_count, then unassigned_priority, then cost, with components that add up to the cost. | objective.costs, summary.score, summary.score.components | How plans are compared |
| Travel engine, matrix | Travel times and distances between every location in the request, fetched from road data per vehicle profile. The engine picks the data source; departure_time prices traffic at that instant. | travel.engine, travel.departure_time, vehicles[].profile | Fields that control travel data |
| Unassigned, category, reason | A task on no route. Its category says what kind of fix can work (impossible, blocked, priced_out, time_limit); each reason names the constraint that refused it. | unassigned[], unassigned[].category, unassigned[].reasons[].constraint | Unassigned jobs |
| Violation | A hard rule your plan breaks, reported by evaluate on the stop or route that breaks it, with a stable code and how far over the limit it is. A solve result never has one. | violations[].code, summary.score.violation_count | Violations |
| Suggestion, insertion | For each task outside the plan you sent, a ranked list of feasible positions, cheapest first. Each insertion gives the cost delta, the stops it adds (placements) and the changed routes. The plan is not modified. | suggestions[], suggestions[].insertions[] | The response |
| Run | An asynchronous solve: the same request body, answered at once with an id and a status that moves from queued to running to succeeded, failed or cancelled. The plan is fetched from /result. | POST /v3/routing/runs, status | The life of a run |
resources[] for vehicles[] and allowedResources for eligible_vehicles. Migration from V2 maps them field by field.