> ## Documentation Index
> Fetch the complete documentation index at: https://developers.kardinal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> If you're integrating Kardinal into an application with an SDK, start with Integration paths: https://developers.kardinal.ai/getting-started/integration-paths.md. It lists the sections to read, in order. If you follow Integration paths, you don't need llms-full.txt or openapi.yaml. Each step links the section you need.

# Multi-day trips

> Write a tour that lasts several days: one rest per night, where each rest falls, how to size the working limits, how to write the times in one time zone, and how to check the nights in a solution.

A multi-day tour is the route of one resource that lasts more than one calendar day. For example, a truck leaves Paris on Monday morning, delivers in Lyon, Marseille, Montpellier and Clermont-Ferrand, and is back on Wednesday evening. A rest is a gap in the tour where the driver sleeps. A night stop is the stop where the vehicle stands during a rest. This guide shows how to write the rests, how to size the limits of the resource, and how to read the times of a long trip. The last section shows how to check a solution.

These snippets use local times where they have times. The plan you put them in needs `"tz"`. See [Dates and time zones](https://developers.kardinal.ai/reference/data-model.md#dates-and-time-zones).

## A window over several days

`workingTimeWindow` is the period when the resource can work. A window that spans several days doesn't force any rest. See [`Resource.workingTimeWindow`](https://developers.kardinal.ai/api-reference/plan/create-a-plan#body-resources) for the rule.

The engine can drive through the evening and the night. In the sandbox, a car with a window over two days and no break drove from 06:00 to 23:53 and finished its last delivery at 00:03 on the second day.

You write each rest yourself, in the `breaks` list of the resource. The next sections show how.

## One rest per night

A `timeWindowBreak` is a rest of a fixed length, inside a window that you give. For one night, write one break:

```json theme={null}
{
  "type": "timeWindowBreak",
  "duration": "PT11H",
  "timeWindow": { "begin": "2026-11-09 19:00", "end": "2026-11-10 07:00" }
}
```

A break covers one night. A trip of N nights needs N breaks. In the sandbox, the example plan with only one break rested on the first night. On the second night, the truck drove from 15:54 to 21:26 and only waited at Clermont-Ferrand. With two breaks, it rested on both nights.

The window is longer than the rest. Here the window lasts 12 hours and the rest lasts 11, so the rest has 1 hour of slack. The exact rule for breaks is in [`Resource.breaks`](https://developers.kardinal.ai/api-reference/plan/create-a-plan#body-resources). The [breaks guide](https://developers.kardinal.ai/guides/breaks.md) shows the other kinds of break.

## Where each rest falls

A break only starts where the vehicle stands. It starts at the start of the tour or at a stop, never in the middle of a drive. See [Where a break can fall](https://developers.kardinal.ai/guides/breaks.md#where-a-break-can-fall).

With a window of 19:00 to 07:00 and a rest of 11 hours, the rest has to start by 20:00 to end by 07:00. The vehicle must therefore finish its work at the night stop by 20:00. It can stand at that stop long before the window opens. In the example plan, the truck is at Lyon from 11:16 in production and from 14:30 in the sandbox. It finishes its work there at 14:30 in production and at 15:00 in the sandbox, then waits until the rest ends.

Don't plan a drive that covers the whole time the rest could start. The engine can't place the rest before that drive or after it. It then leaves unplaced the stops that need the drive. It returns no error. To avoid it, give the route a stop where each night can fall. Use the last delivery of the day, or add a stop for the night. See [Where a break can fall](https://developers.kardinal.ai/guides/breaks.md#where-a-break-can-fall) for a worked example.

A sliding break can also serve as a rest, for example a `workingDurationSlidingBreak` of 11 hours after 13 hours of work. It can add the rest twice. In a sandbox test, the first day ended with a drive of 14 hours 38. The engine added 22 hours of rest at the first stop, which is two rests of 11 hours. When the next stop opened on the morning of day 2, the engine left it unplaced. A `travelDurationSlidingBreak` used as a night rest gave the same 22-hour rest after a long first leg. After a short first leg, it gave a rest in the afternoon, followed by a drive in the night. A `timeWindowBreak` fixes where the night falls, so it is the one to use. A sliding break may be added on top of the night windows when each day's work stays under its limit. In a test with the [heavy long distance case study](https://developers.kardinal.ai/case-studies/heavy-long-distance.md), the tours were the same with and without it. See [Where a break can fall](https://developers.kardinal.ai/guides/breaks.md#where-a-break-can-fall) for the rules of the sliding breaks.

The example models only the night rest. It doesn't model the daily driving limits of a driver. See [Three kinds of break](https://developers.kardinal.ai/guides/breaks.md#three-kinds-of-break) and [The engine's break is not a legal break](https://developers.kardinal.ai/guides/breaks.md#the-engine’s-break-is-not-a-legal-break).

## Sizing the working limits

`maxWorkingDuration` is the longest tour a resource can make. It counts the whole tour, from the departure to the end. It includes the rests and the waits. See [`Resource.maxWorkingDuration`](https://developers.kardinal.ai/api-reference/plan/create-a-plan#body-resources) and [Resource limits](https://developers.kardinal.ai/guides/resource-limits.md#maximum-working-time).

Size it for the whole trip, from the first departure to the last return. A cap sized for one day rules out the tour, with no error. For example, a trip of two days with one rest can have 13 hours of work, then the rest of 11 hours, then 13 hours of work. The cap for this trip is `PT37H`.

For the example plan, the sandbox tour lasts 61 hours 28 and the production tour lasts 57 hours 28. Use the longer duration. In the sandbox:

* A cap of `PT62H` kept all four stops.
* A cap of `PT55H` kept only Lyon.
* A cap of `PT13H` planned nothing.

The cap doesn't include a margin for you. Check the duration of your own trip in the sandbox and in production, and set the cap from the longer one.

The end of `workingTimeWindow` must also hold the drive back to the `arrival`. In the example, the sandbox tour ends at 19:28 on the last day, inside the window that ends at 20:00. See [Working hours](https://developers.kardinal.ai/guides/resource-limits.md#working-hours).

## Time zones on a long trip

A plan has one `tz`, and every time you write is read in that zone. Convert each time into that zone before you write it. This includes the windows of the rests.

For example, the plan has `"tz": "Europe/Paris"`. A customer in Lisbon is open from 09:00 to 12:00 Lisbon time. Lisbon is one hour behind Paris in winter, so you write the window `10:00` to `13:00`. A rest that must fall between 18:00 and 06:00 in Lisbon is written 19:00 to 07:00. The solution comes back in the zone of the plan, with its offset. A stop that the solution shows at `10:00:00+01:00` is at 09:00 in Lisbon. Don't send a different zone for a single stop.

Write every time in the same form: a space between date and time, and no seconds. A trip that crosses midnight uses the same form. See [Dates and time zones](https://developers.kardinal.ai/reference/data-model.md#dates-and-time-zones) for the rules.

Take care on the night when the clocks change. When the clocks go forward, a window from 19:00 to 07:00 lasts 11 hours, not 12. In the sandbox, on the night of March 27 to 28, 2027, the truck could finish its work at the stop only at 19:48. The rest had to start at 19:00 to fit 11 hours into a window of 11 hours. The engine couldn't place it. The whole tour was impossible: the truck stayed unused and both stops were unplaced, with no error. With a shorter first leg, the same rest fitted and ended at 07:00. When the clocks go back, the same window lasts 13 hours.

On the night the clocks go forward, the latest start of the rest comes 1 hour earlier. If your system writes the same window every night, end it 1 hour later than you would on a normal night. A vehicle that may finish its work as late as 20:00 needs a window that ends at 07:00 on a normal night, so write 19:00 to 08:00. A window that opens earlier, such as 18:00 to 07:00, doesn't help, because the rest still has to end by 07:00. See [Dates and time zones](https://developers.kardinal.ai/reference/data-model.md#dates-and-time-zones).

## Checking the solution

A rest is in the solution as a break waypoint. A waypoint is one line of a tour: the start, each stop, each break, and the end. The break waypoint follows a stop, and the vehicle reaches it with no drive.

The length of the break waypoint isn't the length of the rest. The waypoint can include a wait. See [Checking the solution](https://developers.kardinal.ai/guides/breaks.md#checking-the-solution) for what a solution can and can't prove about a break.

To check a night, read the stop before the rest and the stop after it. The vehicle must reach the second stop on a later calendar day. The break waypoint between them must come with zero travel. This proves where the rest falls. It doesn't prove how long it lasts: the length is the `duration` that you wrote in the plan.

### Example plan

One truck leaves Paris on 9 November at 06:00 and serves four customers over three days. It has one rest per night. Each stop has a time window.

```json theme={null}
{
  "tz": "Europe/Paris",
  "maxOptimizationDuration": "PT5S",
  "resources": [
    {
      "id": "truck-1",
      "vehicleProfile": { "type": "truck" },
      "workingTimeWindow": { "begin": "2026-11-09 06:00", "end": "2026-11-11 20:00" },
      "departure": { "lon": 2.36, "lat": 48.75 },
      "arrival": { "lon": 2.36, "lat": 48.75 },
      "breaks": [
        { "type": "timeWindowBreak", "duration": "PT11H", "timeWindow": { "begin": "2026-11-09 19:00", "end": "2026-11-10 07:00" } },
        { "type": "timeWindowBreak", "duration": "PT11H", "timeWindow": { "begin": "2026-11-10 19:00", "end": "2026-11-11 07:00" } }
      ]
    }
  ],
  "orders": [
    {
      "id": "order-lyon",
      "stops": [
        { "type": "single", "id": "stop-lyon", "kind": "delivery", "position": { "lon": 4.85, "lat": 45.75 }, "operationDuration": "PT30M",
          "authorizedTimeWindows": [{ "begin": "2026-11-09 14:00", "end": "2026-11-09 18:00" }] }
      ]
    },
    {
      "id": "order-marseille",
      "stops": [
        { "type": "single", "id": "stop-marseille", "kind": "delivery", "position": { "lon": 5.37, "lat": 43.30 }, "operationDuration": "PT30M",
          "authorizedTimeWindows": [{ "begin": "2026-11-10 10:00", "end": "2026-11-10 14:00" }] }
      ]
    },
    {
      "id": "order-montpellier",
      "stops": [
        { "type": "single", "id": "stop-montpellier", "kind": "delivery", "position": { "lon": 3.88, "lat": 43.61 }, "operationDuration": "PT30M",
          "authorizedTimeWindows": [{ "begin": "2026-11-10 15:00", "end": "2026-11-10 19:00" }] }
      ]
    },
    {
      "id": "order-clermont",
      "stops": [
        { "type": "single", "id": "stop-clermont", "kind": "delivery", "position": { "lon": 3.09, "lat": 45.78 }, "operationDuration": "PT30M",
          "authorizedTimeWindows": [{ "begin": "2026-11-11 10:00", "end": "2026-11-11 14:00" }] }
      ]
    }
  ]
}
```

The same plan with the SDKs:

```python Python theme={null}
from kardinal.routing import models
from kardinal.routing.plans import Order, PlanCreate

paris = models.Position(lon=2.36, lat=48.75)

def night(begin, end):
    return models.TimeWindowBreak(
        type="timeWindowBreak",
        duration="PT11H",
        timeWindow=models.TimeWindow(begin=begin, end=end),
    )

def delivery(name, lon, lat, begin, end):
    stop = models.SingleStop(
        type="single",
        id=f"stop-{name}",
        kind="delivery",
        position=models.Position(lon=lon, lat=lat),
        operationDuration="PT30M",
        authorizedTimeWindows=[models.TaggedTimeWindow(begin=begin, end=end)],
    )
    return Order(id=f"order-{name}", stops=[stop])

truck = models.Resource(
    id="truck-1",
    vehicleProfile=models.VehicleProfileTruck(type="truck"),
    workingTimeWindow=models.TimeWindow(begin="2026-11-09 06:00", end="2026-11-11 20:00"),
    departure=paris,
    arrival=paris,
    breaks=[
        night("2026-11-09 19:00", "2026-11-10 07:00"),
        night("2026-11-10 19:00", "2026-11-11 07:00"),
    ],
)

plan = PlanCreate(
    tz="Europe/Paris",
    maxOptimizationDuration="PT5S",
    resources=[truck],
    orders=[
        delivery("lyon", 4.85, 45.75, "2026-11-09 14:00", "2026-11-09 18:00"),
        delivery("marseille", 5.37, 43.30, "2026-11-10 10:00", "2026-11-10 14:00"),
        delivery("montpellier", 3.88, 43.61, "2026-11-10 15:00", "2026-11-10 19:00"),
        delivery("clermont", 3.09, 45.78, "2026-11-11 10:00", "2026-11-11 14:00"),
    ],
)
```

```ts TypeScript theme={null}
import type { PlanCreateInput } from "@kardinal-ai/sdk";

const paris = { lon: 2.36, lat: 48.75 };

function night(begin: string, end: string) {
  return { type: "timeWindowBreak" as const, duration: "PT11H", timeWindow: { begin, end } };
}

function delivery(name: string, lon: number, lat: number, begin: string, end: string) {
  return {
    id: `order-${name}`,
    priority: 0,
    stops: [
      {
        type: "single" as const,
        id: `stop-${name}`,
        kind: "delivery" as const,
        position: { lon, lat },
        operationDuration: "PT30M",
        authorizedTimeWindows: [{ begin, end }],
      },
    ],
  };
}

const plan: PlanCreateInput = {
  tz: "Europe/Paris",
  maxOptimizationDuration: "PT5S",
  resources: [
    {
      id: "truck-1",
      priority: 0,
      vehicleProfile: { type: "truck" },
      workingTimeWindow: { begin: "2026-11-09 06:00", end: "2026-11-11 20:00" },
      departure: paris,
      arrival: paris,
      breaks: [
        night("2026-11-09 19:00", "2026-11-10 07:00"),
        night("2026-11-10 19:00", "2026-11-11 07:00"),
      ],
    },
  ],
  orders: [
    delivery("lyon", 4.85, 45.75, "2026-11-09 14:00", "2026-11-09 18:00"),
    delivery("marseille", 5.37, 43.3, "2026-11-10 10:00", "2026-11-10 14:00"),
    delivery("montpellier", 3.88, 43.61, "2026-11-10 15:00", "2026-11-10 19:00"),
    delivery("clermont", 3.09, 45.78, "2026-11-11 10:00", "2026-11-11 14:00"),
  ],
};
```

### What the solution shows

Production returns this tour for the plan, with the offset of `Europe/Paris` and with seconds. The other fields are left out. The times come from a production run on 2026-11-03. The sandbox draws every drive as a straight line, so its times differ: the first drive, Paris to Lyon, took 8 hours 30 in the sandbox and 5 hours 17 in production.

```json theme={null}
{
  "resourceId": "truck-1",
  "isValid": true,
  "wayPoints": [
    { "type": "begin", "departureTime": "2026-11-09T06:00:00+01:00" },
    { "type": "stop", "stopId": "stop-lyon", "arrivalTime": "2026-11-09T11:16:47+01:00", "departureTime": "2026-11-09T14:30:00+01:00", "fromPrevious": { "travelDuration": "PT5H16M47S" } },
    { "type": "break", "arrivalTime": "2026-11-09T14:30:00+01:00", "departureTime": "2026-11-10T06:00:00+01:00", "fromPrevious": { "travelDuration": "PT0S" } },
    { "type": "stop", "stopId": "stop-marseille", "arrivalTime": "2026-11-10T09:42:09+01:00", "departureTime": "2026-11-10T10:30:00+01:00", "fromPrevious": { "travelDuration": "PT3H42M9S" } },
    { "type": "stop", "stopId": "stop-montpellier", "arrivalTime": "2026-11-10T12:34:53+01:00", "departureTime": "2026-11-10T15:30:00+01:00", "fromPrevious": { "travelDuration": "PT2H4M53S" } },
    { "type": "break", "arrivalTime": "2026-11-10T15:30:00+01:00", "departureTime": "2026-11-11T06:00:00+01:00", "fromPrevious": { "travelDuration": "PT0S" } },
    { "type": "stop", "stopId": "stop-clermont", "arrivalTime": "2026-11-11T10:08:12+01:00", "departureTime": "2026-11-11T10:38:12+01:00", "fromPrevious": { "travelDuration": "PT4H8M12S" } },
    { "type": "end", "arrivalTime": "2026-11-11T15:28:12+01:00", "fromPrevious": { "travelDuration": "PT4H50M" } }
  ]
}
```

* All four stops are planned, and `unaffectedStopIds` is empty.
* Each break waypoint comes right after a stop, with a travel time of `PT0S`. Night 1 is at Lyon and night 2 is at Montpellier.
* The first break waypoint lasts 15 hours 30, for a rest of 11 hours. It includes the wait at Lyon between the end of the delivery at 14:30 and the start of the rest at 19:00. The earlier wait, from 11:16 to 14:00, is in the stop waypoint, not in the break one. See [Checking the solution](https://developers.kardinal.ai/guides/breaks.md#checking-the-solution).
* The truck reaches Marseille on 10 November, the day after Lyon. It reaches Clermont-Ferrand on 11 November, the day after Montpellier. Both nights are rests.
* The tour lasts 57 hours 28, from the departure on 9 November at 06:00 to the end on 11 November at 15:28. The sandbox tour lasts 61 hours 28.

### A check for each night

This check reads a tour and the `tz` of the plan. It looks at each pair of consecutive stops, from the start to the end. When the second stop is reached on a later calendar day, the vehicle must have rested between them. A break waypoint that ends on a later day than it starts is a rest. A break that stays on one day, such as a daytime break, is not a rest. The check also flags a break that comes after a drive. It returns the nights that fail.

```python Python theme={null}
from datetime import datetime
from zoneinfo import ZoneInfo

def local_day(text, tz):
    """Return the calendar day of an ISO 8601 time, in the zone of the plan."""
    return datetime.fromisoformat(text).astimezone(ZoneInfo(tz)).date()

def check_nights(tour, tz):
    """Return the nights where the vehicle doesn't rest."""
    problems = []
    previous, rested = None, False
    for point in tour["wayPoints"]:
        if point["type"] == "break":
            if point["fromPrevious"]["travelDuration"] != "PT0S":
                problems.append(f"the break at {point['arrivalTime']} comes after a drive")
            if local_day(point["departureTime"], tz) > local_day(point["arrivalTime"], tz):
                rested = True
            continue
        day = local_day(point.get("arrivalTime") or point["departureTime"], tz)
        if previous and day > previous and not rested:
            problems.append(f"no rest between the stop reached on {previous} and the one reached on {day}")
        previous, rested = day, False
    return problems
```

```ts TypeScript theme={null}
type WayPoint = {
  type: string;
  arrivalTime?: string;
  departureTime?: string;
  fromPrevious?: { travelDuration?: string };
};

// Return the calendar day of an ISO 8601 time, in the zone of the plan.
function localDay(text: string, tz: string): string {
  return new Intl.DateTimeFormat("en-CA", { timeZone: tz }).format(new Date(text));
}

// Return the nights where the vehicle doesn't rest.
function checkNights(tour: { wayPoints: WayPoint[] }, tz: string): string[] {
  const problems: string[] = [];
  let previous: string | undefined;
  let rested = false;
  for (const point of tour.wayPoints) {
    if (point.type === "break") {
      if (point.fromPrevious?.travelDuration !== "PT0S") {
        problems.push(`the break at ${point.arrivalTime} comes after a drive`);
      }
      if (localDay(point.departureTime!, tz) > localDay(point.arrivalTime!, tz)) rested = true;
      continue;
    }
    const day = localDay((point.arrivalTime ?? point.departureTime)!, tz);
    if (previous && day > previous && !rested) {
      problems.push(`no rest between the stop reached on ${previous} and the one reached on ${day}`);
    }
    previous = day;
    rested = false;
  }
  return problems;
}
```

For this tour, the check returns an empty list. This check shows where each rest falls. It doesn't show the length of the rest: the length is the `duration` of the break in your plan. It also doesn't look at the daily driving limits. Then read `unaffectedStopIds`, the list of stops that the engine left out.

See [Handling infeasibility](https://developers.kardinal.ai/guides/handling-infeasibility.md) to find the reason for each stop in that list.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.