Data model

This page is a map, not a field reference: each section below is a short orientation to one part of the plan, linking straight to the schema panel of the API reference that actually documents every field, type, and constraint — that’s where to look up a specific field’s full definition. A plan is built from two lists — resources (vehicles/drivers) and orders (what needs to be done) — plus plan-level fields that add constraints spanning several of them. See First API call for the request/response shapes and How the optimization engine works for what the engine does with these fields.

​

Resource (vehicle-driver pair)

One vehicle-driver pair for the duration of the plan — id, working hours, capacities, skills, breaks, and travel constraints. See the resources schema.

​

Vehicle profiles

Mode of transport and its travel constraints (fly, pedestrian, bicycle, scooter, motorbike, car, truck), nested under each resource’s vehicleProfile. The fly profile additionally takes a kmph field — a constant travel speed used to compute crow-fly travel times, since it has no road network to derive one from. On a truck profile, height, width, and length are in metres and grossWeight in kilograms. See the resources schema.

​

Order, stop

An order is one or more stops that must all be planned onto the same resource, in array order. See the orders schema. A stop’s kind (pickup, delivery, or acknowledgement) sets which way its capacities move, from the resource’s point of view: a pickup loads its quantity at the stop, and a delivery unloads it there. A negative quantity reverses that direction: a delivery of -100 has the same effect as a pickup of 100. Within one order, a pickup and a delivery carry the same goods: the resource loads them at the first stop and unloads them at the second. A delivery whose order has no pickup is assumed loaded at departure, which shows in the tour’s filledCapacitiesAtBegin. Pickups and deliveries from different orders are distinct goods, even when their quantities match.

​

Capacities

Free-form map tracking what a resource carries and what a stop consumes or releases, declared on both resources and stops. See the resources and orders schemas. A solution reports filledCapacitiesAtBegin/filledCapacitiesAtEnd/filledCapacitiesAfterStop (capacities loaded at the start, end, and after each stop) and maxFilledCapacities (the peak reached during the tour) — see the Tour and WayPointStop schemas in the API reference. A capacity declared on a resource with a ceiling no tour can reach reads back as a read-only KPI (for example nbPackages) without affecting the optimization.

​

Shared capacity pools

Plan-level sharedCapacities flag pooling a capacity key across all of a resource’s stops, regardless of order. See the sharedCapacities schema.

​

Time windows

TimeWindow (plain {begin, end}) and TaggedTimeWindow (the same shape plus optional resourceTags), used for working hours, breaks, and a stop’s authorized/preferred windows. See the resources and orders schemas.

​

Breaks

A resource’s breaks array, mixing timeWindowBreak, workingDurationSlidingBreak, and travelDurationSlidingBreak entries. See the resources schema.

​

Constraints catalog

additionalConstraints (scoped to specific tags) and globalConstraints (scoped to the whole fleet) beyond what resources/orders/stops express directly. See the additionalConstraints and globalConstraints schemas.

​

Plan-level fields

Fields that configure the plan as a whole: agencyId, tz, lateDeparture, maxOptimizationDuration, sharedCapacities, objectives, additionalConstraints, globalConstraints, accessDurationsByStopTag, overlappingCapacitiesByStopTag, setupDurations, additionalOperationDurations. See the Plan schema.

​

Status and state

Two read-only fields track a plan’s lifecycle: status (a detailed breakdown per stage — waiting room, creation, optimization, and traffic fetching) and state (a single summary value, optimized once no better solution can be found). See How the optimization engine works for the full polling pattern, and GET /plans/{planId}/state to retrieve state directly.

​

Positions and geocoding

Every position in a plan (each stop’s position, and a resource’s departure/arrival) is a {lat, lon} pair in decimal degrees. The API does not geocode addresses: geocode them on your side before building the plan, with whichever geocoding provider your integration already uses. If you can’t geocode your addresses yourself, contact customer.success@kardinal.ai: the team can geocode an address set for you on request. A wrongly geocoded position raises no error: it silently routes to the wrong place. Spot-check a sample of geocoded stops on a map before submitting. If an address can’t be geocoded precisely, treat it as a data-quality gap rather than falling back to an approximation such as a town or postal-code centroid, since stops sharing that point collapse onto it. See §5 of the AI agent checklist, and Geocoding and addresses for the questions to settle with the operations team.

​

Depot vs. position

Depots are not first-class objects in this API — there is no Depot schema. A resource’s departure/arrival positions (a raw {lat, lon}, or "atFirstPosition" for arrival) are how a depot is represented: resolve it to its position on the client side before building the plan. A “depot” tag such as "depot:main" (see Multi-trip tours) is an arbitrary stop tag your integration defines, not a reference to any API object. See the resources schema.

​

See also

• Hard vs soft constraints — which of the preceding bend under pressure and which don’t.
• Modeling advanced constraints — worked examples for capacities, skills, breaks, time windows, and optional steps that gate a mandatory stop.
• How the optimization engine works — objectives and the optimization loop that consumes this data.