Skip to main content
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.

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 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:
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. The breaks guide 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. 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 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, the tours were the same with and without it. See 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 and 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 and Resource limits. 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.

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 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.

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 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.
The same plan with the SDKs:

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.
  • 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.
  • 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.
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 to find the reason for each stop in that list.