Skip to content

The Problem object (request)

Reference · API reference

Everything is wrapped in a single problem object.

{
  "problem": {
    "fleet":         [ … ],
    "jobs":          [ … ],
    "objective":     1,
    "configuration": { … }
  }
}
Field Required What it is
problem ✅ The wrapper. Everything below lives inside it.
problem.fleet[] ✅ The vehicles available.
problem.jobs[] ✅ The work to route.
problem.objective — The outcome to optimize for. Default 1. See Enums.
problem.configuration — Units, polylines, and constraint switches.

objective and configuration go inside problem

Placing them next to problem rather than inside it is the most common payload mistake, and the engine will not apply them.

problem.fleet[] — your vehicles

At least one vehicle. Each vehicle:

Field Required Notes
id ✅ Unique integer.
capacities[] ✅ Named buckets: { "name": "parcels", "units": 40 }. The names are what a task's demand refers to.
shifts[] — Working periods (see below).
skills[] — Skills the vehicle/driver provides, matched to job skills.
limits — { maxDistance, maxStops, lifoDepth }.
lastKnownLocation — Current position (re-optimization only).
routeTemplateId — Apply a saved template (v1.1+).
maxInstances — Max route instances this vehicle may run.

Shift — start and end each have a time (ISO 8601 with offset) and a location. Optional breaks[], each with a serviceWindow, duration (seconds), and location.

{
  "id": 1,
  "capacities": [{ "name": "parcels", "units": 40 }],
  "shifts": [{
    "start": { "time": "2026-07-31T08:00:00-07:00", "location": [49.28270, -123.11540] },
    "end":   { "time": "2026-07-31T17:00:00-07:00", "location": [49.28270, -123.11540] },
    "breaks": [{ "serviceWindow": ["2026-07-31T12:00:00-07:00", "2026-07-31T13:00:00-07:00"], "duration": 1800 }]
  }]
}

problem.jobs[] — the work

At least one job. Each job has an id and pickups and/or deliveries — arrays of task objects.

Task fields:

Field Required Notes
id ✅ Unique integer.
location ✅ [lat, lng] or { "lat":…, "lng":… }. Use ≥ 5 decimals.
serviceWindows[] ✅ Allowed time ranges, each a [start, end] array. See the note below.
duration — Service time at the stop, in seconds.
demand[] — Capacity consumed: { "name": "parcels", "units": 2 }, matched to the vehicle's capacities by name.
skills[] — Skills this task requires.
status — pending / in_progress / performed (re-optimization).
vehicleId, eta — Current assignment/ETA (re-optimization). 
{
  "id": 101,
  "deliveries": [{
    "id": 1001,
    "location": [49.26340, -123.13830],
    "serviceWindows": [["2026-07-31T09:00:00-07:00", "2026-07-31T12:00:00-07:00"]],
    "duration": 300,
    "demand": [{ "name": "parcels", "units": 2 }]
  }]
}

Every task needs a service window

serviceWindows is not optional in practice. A task without one is rejected with 400 Cannot read property 'timeRange' of undefined. When a stop genuinely has no constraint, give it the vehicle's shift window — deliver any time the vehicle is on the road.

Job types

A job can be pickup-only, delivery-only, or pickup-and-delivery. What it can't be: multiple pickups and multiple deliveries in the same job. See Enums, limits and rules.

Related: The Solution object · Enums, limits and rules · Recipes