Concepts

​

Jobs

{
  "id": "delivery-1",
  "location": { "coordinate": [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"
    }
  ],
  "demand": { "weight": 10 },
  "skills": [{ "name": "refrigerated" }]
}

• location — a Place: { "coordinate": [lon, lat] } (GeoJSON order), inline only — there is no reference into a separate locations/depot list. Omit it entirely for a virtual (location-less) job.
• service_duration_s — nominal seconds spent at the location, excluding travel; scaled by the serving vehicle’s service_factor.
• time_windows — when the job can be served (ISO 8601 from/to pairs). Hard by default. Lateness is softened fleet-wide via objective.costs.per_late_hour, per-task via target_arrival, or graded between a task’s own alternative windows via time_windows[].cost — see Constraints for how the three compose.
• demand — named capacity consumed, e.g. { "weight": 10 }. Matched against vehicle.capacity by name.
• skills — capability requirements, e.g. [{ "name": "refrigerated" }]. A job can only be served by a vehicle that has all required skills; there is no soft-skill form.
• mandatory — omit or set true to require the job be served (infeasible if it cannot be). false makes it droppable, and only means something together with drop_fee (below) — a droppable task with no price is rejected.
• drop_fee — what leaving the job unserved costs, in the objective’s currency. Replaces the removed unassigned_cost field.

​

Shipments

{
  "id": "ship-7",
  "demand": { "weight": 50 },
  "pickup":   { "location": { "coordinate": [4.30, 50.80] }, "service_duration_s": 120 },
  "delivery": { "location": { "coordinate": [4.50, 50.90] }, "service_duration_s": 120 }
}

​

Vehicles

{
  "id": "truck-1",
  "capacity": { "weight": 1000, "volume": 50 },
  "skills": ["refrigerated"],
  "limits": {
    "max_distance_m": 250000,
    "max_route_duration_s": 32400
  },
  "shifts": [
    {
      "from": "2026-04-01T08:00:00+02:00",
      "to":   "2026-04-01T17:00:00+02:00",
      "start": { "coordinate": [4.3517, 50.8503] },
      "end":   { "coordinate": [4.3517, 50.8503] }
    }
  ]
}

• capacity — named dimension limits matched against job/shipment demand by name. { "weight": 1000, "volume": 50 } is two independent caps.
• skills — capability tags the vehicle provides. A vehicle can serve a job only when its skills are a superset of the job’s required skills.
• limits — optional hard route caps: max_distance_m and max_route_duration_s. The latter caps the whole-route span from shift departure to final arrival — travel, service, and wait all count, not pure driving time; there is no separate pure-drive-time cap.
• shifts — working time windows (ISO 8601 from/to). At least one shift is required. start and end are the depot Place for this shift — set inside shifts, not at vehicle top-level; absent means an open start/end on that side. shifts[].max_tasks caps the number of stops in that shift; shifts[].breaks/shifts[].reloads add driver breaks and multi-trip depot reloads (see Constraints).

​

Distance matrices

​

Constraints

​

Objective

1. Drop penalty (tier 1) — the summed penalty of unassigned tasks. A must-serve task (the default) carries a large uniform internal penalty, so on a request with no drop_fee set this tier is exactly “number of unassigned tasks” and always outranks cost.
2. Cost (tier 2) — the weighted currency sum of travel, waiting, overtime, soft lateness, preference violations, and the drop_fee of every priced task the plan chose not to serve.

{
  "objective": {
    "minimize_vehicles": true,
    "costs": { "per_travel_hour": 50.0, "per_travel_km": 0.20, "currency": "EUR" }
  }
}

​

Relations

{
  "relations": [
    {
      "type": "ordered",
      "job_ids": ["pickup-A", "delivery-A", "delivery-B"]
    },
    {
      "type": "same_resource",
      "job_ids": ["monday-visit", "tuesday-followup"]
    }
  ]
}