Break Management

Breaks are essential for driver safety, legal compliance, and operational efficiency. This guide covers how to configure various break types, locations, and timing constraints in your routing optimization.

Break Configuration Basics

Breaks are defined within resource shifts:

{
  "resources": [
    {
      "name": "driver-1",
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T17:00:00Z",
        "breaks": [
          {
            "type": "WINDOWED",
            "from": "2024-03-15T12:00:00Z",
            "to": "2024-03-15T13:00:00Z",
            "duration": 3600  // 1 hour break
          }
        ]
      }]
    }
  ],
  "jobs": [
    {
      "name": "delivery-1",
      "duration": 1800
    }
  ]
}

Break Types

Windowed Breaks

Can occur flexibly within a time window:

{
  "breaks": [
    {
      "type": "WINDOWED",
      "from": "2024-03-15T12:00:00Z",
      "to": "2024-03-15T13:00:00Z",
      "duration": 3600  // Break duration in seconds
    }
  ]
}

Flexible Windowed Breaks

Flexible timing within a wider window:

{
  "breaks": [
    {
      "type": "WINDOWED",
      "from": "2024-03-15T11:00:00Z",
      "to": "2024-03-15T14:00:00Z",
      "duration": 2700  // 45 minutes anytime in window
    }
  ]
}

Drive Breaks

Reset continuous driving time:

{
  "breaks": [
    {
      "type": "DRIVE",
      "driveTime": 16200,  // After 4.5 hours driving
      "duration": 2700      // 45 minutes break
    }
  ]
}

Duty Breaks

Trigger a break after cumulative work time — the combined total of driving time and service time. Unlike drive breaks which only count time behind the wheel, duty breaks account for all active work performed by the resource.

{
  "breaks": [
    {
      "type": "DUTY",
      "workTime": 19800,  // After 5.5 hours of total work
      "duration": 1800     // 30 minutes break
    }
  ]
}

Work time calculation: Work time includes driving time and service time (job durations). It does not include waiting time from time windows, break time, or synchronization delays.

Unavailability Breaks

Mark resource as unavailable:

{
  "breaks": [
    {
      "type": "UNAVAILABILITY",
      "from": "2024-03-15T14:00:00Z",
      "to": "2024-03-15T15:00:00Z"
    }
  ]
}

Break Locations

Location Options

No Location
Specific Location
Start and End Location

{
  "type": "WINDOWED",
  "from": "2024-03-15T11:00:00Z",
  "to": "2024-03-15T14:00:00Z",
  "duration": 1800
}

A WINDOWED break has no location of its own: it is taken wherever the resource is

{
  "type": "UNAVAILABILITY",
  "from": "2024-03-15T11:00:00Z",
  "to": "2024-03-15T14:00:00Z",
  "start": {
             "latitude": 51.048,
             "longitude": 3.696
           }
}

Break at designated rest area

{
  "type": "UNAVAILABILITY",
  "from": "2024-03-15T11:00:00Z",
  "to": "2024-03-15T14:00:00Z",
  "start": {
             "latitude": 51.048,
             "longitude": 3.696
           },
  "end": {
           "latitude": 51.062,
           "longitude": 3.731
         }
}

Break starting and ending at different locations

Location Impact:

WINDOWED, DRIVE and DUTY breaks have no location and add no travel time
UNAVAILABILITY with start: travel time to the start location is accounted for

Unavailability Start and End Locations

An unavailability break can carry a start and an end location. The resource travels from its previous stop to start before the break, and resumes from end after it — travel between start and end during the break is considered instantaneous and is not the solver’s concern. This models fixed commitments at known places, such as locked appointments overlaid on availability, without splitting availability into separate blocks.

start and end are both optional; setting end requires start.
If only start is given, end defaults to start.
The legacy location field is still accepted and is equivalent to setting start and end to the same location. It cannot be combined with start/end.
If the break falls after the last job of a route, the return leg to the shift end starts from the break’s end location, and the route cannot finish before the break’s to time.

Deducting Previous Breaks

When a shift includes multiple breaks, you can use deductPreviousBreaks to reduce a break’s effective duration by the total time already spent on earlier breaks. This is useful when regulations require a total rest period that can be split across multiple shorter breaks throughout the shift.

{
  "breaks": [
    {
      "type": "WINDOWED",
      "from": "2024-03-15T10:00:00Z",
      "to": "2024-03-15T10:30:00Z",
      "duration": 900
    },
    {
      "type": "DUTY",
      "workTime": 21600,
      "duration": 2700,
      "deductPreviousBreaks": true
    }
  ]
}

In this example, the duty break has a base duration of 45 minutes (2700 seconds). Because deductPreviousBreaks is true, the 15-minute windowed break taken earlier is subtracted, resulting in an effective duty break of only 30 minutes.

How deduction works: When deductPreviousBreaks is true, the effective break duration is calculated as:effective duration = max(0, break duration − break time already taken)Break time already taken is what earlier breaks actually took, each at its own effective duration, so a deducting break tops the rest taken so far up to its configured duration. If earlier breaks already meet or exceed it, the effective duration becomes zero — the break is still tracked but adds no extra idle time.

Chained deductions add up to the largest configured duration. With a 15-minute windowed break, a 30-minute DUTY break and a 45-minute DRIVE break, both deducting, a route that triggers all three takes 15 + 15 + 15 minutes:

Break	Configured	Already taken	Effective
`WINDOWED`	900	0	900
`DUTY` (`deductPreviousBreaks: true`)	1800	900	900
`DRIVE` (`deductPreviousBreaks: true`)	2700	1800	900

Each visit’s breakTime reports the effective duration of the breaks taken before it. The deductPreviousBreaks option is available on all trigger-based break types:

Break type	Field	Default
`WINDOWED`	`deductPreviousBreaks`	`false`
`DRIVE`	`deductPreviousBreaks`	`false`
`DUTY`	`deductPreviousBreaks`	`false`

Break Timing Constraints

Break Before Finish

There is no separate shift-level field for “break must finish by”. The to bound of a WINDOWED break is not a hard deadline: a window that has closed is still charged, and with a single break per shift the bound has little effect. Where a hard bound is needed, use an UNAVAILABILITY break, which blocks its from to to interval:

{
  "shifts": [{
    "from": "2024-03-15T08:00:00Z",
    "to": "2024-03-15T17:00:00Z",
    "breaks": [{
      "type": "UNAVAILABILITY",
      "from": "2024-03-15T14:00:00Z",
      "to": "2024-03-15T15:00:00Z"  // Resource is unavailable 14:00-15:00
    }]
  }]
}

Breaks After the Last Job

A break that is due once the last job is done is taken before the route ends: it delays the arrival at the shift end and is reported as breakTime on the trip’s end visit.

A DRIVE or DUTY break is due when the return leg to the shift end takes the trip over its threshold. A threshold crossed during a job’s service is handled before that job, so with ignoreTravelTimeFromLastJob no such break is added at the end.
A WINDOWED break that no visit took is due if its window opens before the resource is back, even if the window has closed by then. A window that opens later is not reported.

Deduction applies as on the route: these breaks subtract the break time taken earlier, and each other.

Multiple Breaks Example

{
  "shifts": [{
    "from": "2024-03-15T06:00:00Z",
    "to": "2024-03-15T18:00:00Z",
    "breaks": [
      {
        "type": "WINDOWED",
        "from": "2024-03-15T09:00:00Z",
        "to": "2024-03-15T10:30:00Z",
        "duration": 900  // 15-minute morning break
      },
      {
        "type": "WINDOWED",
        "from": "2024-03-15T11:30:00Z",
        "to": "2024-03-15T13:30:00Z",
        "duration": 3600  // 1-hour lunch
      },
      {
        "type": "WINDOWED",
        "from": "2024-03-15T15:00:00Z",
        "to": "2024-03-15T16:30:00Z",
        "duration": 900  // 15-minute afternoon break
      }
    ]
  }]
}

Integration with Resumable Jobs

An UNAVAILABILITY break can interrupt a long service job, provided the job is marked resumable.

resumable only applies to UNAVAILABILITY breaks. WINDOWED, DRIVE and DUTY breaks are placed between jobs and never interrupt one, so combining them with resumable has no effect. See Resumable Jobs.

{
  "jobs": [
    {
      "name": "installation",
      "duration": 14400,  // 4 hours
      "resumable": true   // Can be paused by an UNAVAILABILITY break
    }
  ],
  "resources": [{
    "name": "driver-1",
    "shifts": [{
      "from": "2024-03-15T08:00:00Z",
      "to": "2024-03-15T17:00:00Z",
      "breaks": [{
        "type": "UNAVAILABILITY",
        "from": "2024-03-15T12:00:00Z",
        "to": "2024-03-15T13:00:00Z"
      }]
    }]
  }]
}

Result: Installation runs 8:00-12:00 (4 hours), break 12:00-13:00, resumes 13:00 to completion

Complex Break Scenarios

Legal Compliance Example

EU driving regulations with both drive and duty breaks:

{
  "resources": [{
    "name": "long-haul-driver",
    "shifts": [{
      "from": "2024-03-15T06:00:00Z",
      "to": "2024-03-15T20:00:00Z",
      "breaks": [
        {
          "type": "DRIVE",
          "driveTime": 16200,  // After 4.5 hours driving
          "duration": 2700      // 45 minutes break
        },
        {
          "type": "DUTY",
          "workTime": 21600,    // After 6 hours total work
          "duration": 1800       // 30 minutes break
        },
        {
          "type": "WINDOWED",
          "from": "2024-03-15T11:00:00Z",
          "to": "2024-03-15T15:00:00Z",
          "duration": 3600  // Daily rest period
        }
      ]
    }]
  }],
  "jobs": [{
    "name": "long-distance-delivery",
    "duration": 1800
  }]
}

Combining DRIVE and DUTY breaks: DRIVE and DUTY breaks trigger independently. A driver with long service stops may hit the DUTY threshold before the DRIVE threshold, or vice versa. Use both when regulations limit driving time and total work time separately. Consider using deductPreviousBreaks on the later breaks to avoid over-scheduling rest when earlier breaks already count toward the required rest period.

Field Service with Breaks

{
  "resources": [{
    "name": "technician",
    "shifts": [{
      "from": "2024-03-15T08:00:00Z",
      "to": "2024-03-15T17:00:00Z",
      "start": {"latitude": 52.520, "longitude": 13.405},
      "breaks": [
        {
          "type": "WINDOWED",
          "from": "2024-03-15T10:00:00Z",
          "to": "2024-03-15T10:30:00Z",
          "duration": 900
        },
        {
          "type": "WINDOWED",
          "from": "2024-03-15T12:00:00Z",
          "to": "2024-03-15T14:00:00Z",
          "duration": 2700
        }
      ]
    }]
  }],
  "jobs": [{
    "name": "service-1",
    "duration": 3600
  }]
}

Best Practices

Plan for Travel Time

UNAVAILABILITY breaks with a start location require travel to that location - position routes accordingly

Use Flexible Windows

Windowed breaks give solver more optimization options than fixed breaks

Consider Job Locations

WINDOWED, DRIVE and DUTY breaks have no location and add no travel; use start/end only when the break must happen at a specific place

Account for Regulations

Implement legal break requirements as hard constraints

Break Impact on Routes

The solver automatically:

Schedules breaks within allowed windows
Triggers duty breaks when cumulative work time exceeds the threshold
Triggers drive breaks when cumulative driving time exceeds the threshold
Adds travel time for UNAVAILABILITY breaks with a start location
Pauses and resumes resumable jobs around UNAVAILABILITY breaks
Ensures breaks don’t violate time windows
Optimizes break placement to minimize disruption

Common Issues:

Insufficient time for breaks at a start location, including travel
Break windows conflicting with job time windows
Too many fixed breaks reducing flexibility

Performance Considerations

Break Complexity Impact

Low Impact:

Single break per shift
Breaks without a location
Wide time windows

Medium Impact:

Multiple breaks per shift
Breaks with start/end locations
Moderate time windows

High Impact:

Many fixed-time breaks
Specific break locations
Tight break windows
Multiple driving and duty breaks combined

Troubleshooting

Breaks Not Scheduled

Causes:

Break window too restrictive
Insufficient time in shift
Travel time to break location too long

Solutions:

Widen break windows
Use breaks without a location (WINDOWED, DRIVE, DUTY) when the place does not matter
Verify shift duration accommodates all breaks

Inefficient Break Placement

Causes:

Fixed breaks at suboptimal times
Break locations causing excessive travel

Solutions:

Use windowed breaks for flexibility
Consider multiple smaller breaks
Place break locations close to the route

Jobs Interrupted by Breaks

Causes:

A non-resumable job overlapping an UNAVAILABILITY break, which pushes it until after the break
Poor break window alignment

Solutions:

Mark long jobs resumable — note this only helps for UNAVAILABILITY breaks
Adjust break windows
Use job relations to control scheduling

Shift Management

Configure shifts and working hours

Resumable Jobs

Jobs that can be paused by an unavailability

Drive Time Limits

Legal driving time restrictions

Time Windows

Coordinate breaks with job timing

Platform

VRP API

Fill API

Break Management

Break Management

Break Configuration Basics

Break Types

Windowed Breaks

Flexible Windowed Breaks

Drive Breaks

Duty Breaks

Unavailability Breaks

Break Locations

Location Options

Unavailability Start and End Locations

Deducting Previous Breaks

Break Timing Constraints

Break Before Finish

Breaks After the Last Job

Multiple Breaks Example

Integration with Resumable Jobs

Complex Break Scenarios

Legal Compliance Example

Field Service with Breaks

Best Practices

Break Impact on Routes

Performance Considerations

Troubleshooting

Shift Management

Resumable Jobs

Drive Time Limits

Time Windows

​Break Management

​Break Configuration Basics

​Break Types

​Windowed Breaks

​Flexible Windowed Breaks

​Drive Breaks

​Duty Breaks

​Unavailability Breaks

​Break Locations

​Location Options

​Unavailability Start and End Locations

​Deducting Previous Breaks

​Break Timing Constraints

​Break Before Finish

​Breaks After the Last Job

​Multiple Breaks Example

​Integration with Resumable Jobs

​Complex Break Scenarios

​Legal Compliance Example

​Field Service with Breaks

​Best Practices

​Break Impact on Routes

​Performance Considerations

​Troubleshooting

​Related Features

Shift Management

Resumable Jobs

Drive Time Limits

Time Windows

Break Management

Break Configuration Basics

Break Types

Windowed Breaks

Flexible Windowed Breaks

Drive Breaks

Duty Breaks

Unavailability Breaks

Break Locations

Location Options

Unavailability Start and End Locations

Deducting Previous Breaks

Break Timing Constraints

Break Before Finish

Breaks After the Last Job

Multiple Breaks Example

Integration with Resumable Jobs

Complex Break Scenarios

Legal Compliance Example

Field Service with Breaks

Best Practices

Break Impact on Routes

Performance Considerations

Troubleshooting

Related Features