Routing with Driver Breaks

RouteCloud can automatically insert driver breaks into routes. Breaks can be specified three ways:

• Legal breaks are inserted at regular intervals. They are specified by setting settings.enable_legal_breaks to true and populating the settings.legal_break_duration and settings.legal_break_interval fields.
• Relative breaks are inserted after a certain number of hours have been worked. They are specified by setting route.breaks_relative_to_start to true and populating the route.breaks field.
• Non-relative breaks are inserted at particular times of the day. They are specified by setting route.breaks_relative_to_start to false and populating the route.breaks field.

The three methods listed above are mutually exclusive. If legal breaks are specified, then any breaks specified on route.breaks are ignored.

Breaks are routed only when they can be completed in their entirety. For example, if a route starts at 11:00 AM and finishes at 2:00 PM, then a 10:00 AM or 3:00 PM break is ignored.

Note

To run the examples in this tutorial, you will need:

• A RouteCloud API login. Use your Verizon Connect Enterprise username and password to authenticate with the RouteCloud API. To obtain a username and password, contact Verizon Connect sales.
• cURL to run the requests. You can download a cURL binary from here.

Legal Driver Breaks

Legal breaks are inserted at regular intervals.

Request

{
  "routes": [
    {
      "id": "route0_route_with_legal_breaks",
      "location": "39.718005, -104.969531",
      "start_time": "09:00"
    }
  ],
  "jobs": [
    { "id": "job0", "location": "39.635928, -105.049219" },
    { "id": "job1", "time_on_site": "01:00", "location": "39.725375, -104.791080" },
    { "id": "job2", "time_on_site": "01:00", "location": "39.708990, -105.026954" },
    { "id": "job3", "time_on_site": "01:00", "location": "39.653975, -105.093750" }
  ],
  "settings": {
    "enable_legal_breaks": true,
    "legal_break_duration": "00:30:00",
    "legal_break_interval": "03:00:00"
  }
}

The routing_with_legal_breaks_build.json build request - download it here.

The routing_with_legal_breaks_build.json request requires a 30 minute break every three hours.

Response

{
  "routes": [
    {
      "id": "route0_route_with_legal_breaks", ...
      "stops": [
        { "type": "depot", "arrival_time": "09:00:00", ... },
        { "type": "job", "arrival_time": "09:26:54", ... },
        { "type": "job", "arrival_time": "10:59:58", ... },
        {
          "type": "legal_break"
          "arrival_time": "11:09:56",
          "time_on_site": "00:30:00",
		  ...
        },
        { "type": "job", "arrival_time": "11:39:56", ... },
        { "type": "job", "arrival_time": "12:55:28", ... },
        { "type": "depot", "arrival_time": "14:08:04", ... }
      ]
    }
  ],
  "unrouted_jobs": []
}

Snipped version of the response - download the full response here. Click here to open it in the UI.

The response shows that there is a 30 minute legal break inserted at 11:09:56. It is inserted here because, if it was any later, then it would occur more than three hours into the route, exceeding the settings.legal_break_interval value of "03:00:00" (3 hours). Legal breaks may occur earlier than expected, but never later than expected.

There is no cascading effect. For example, when a legal break is inserted earlier, the subsequent breaks are not required to occur earlier, and they continue to occur at their scheduled time.

Non-relative Driver Breaks

Non-relative breaks always start at the same time each day.

Request

{
  "routes": [
    {
      "id": "route0_route_with_nonrelative_breaks",
      "location": "39.718005, -104.969531",
      "start_time": "09:00",
      "breaks": [
        { "id": "route0_morning_break", "start": "11:00", "length": "00:15" },
        { "id": "route0_lunch_break", "start": "13:00", "length": "00:30" },
        { "id": "route0_afternoon_break", "start": "15:00", "length": "00:15" }
      ]
    }
  ],
  "jobs": [
    { "id": "job0", "location": "39.635928, -105.049219" },
    { "id": "job1", "time_on_site": "01:00", "location": "39.725375, -104.791080" },
    { "id": "job2", "time_on_site": "01:00", "location": "39.708990, -105.026954" },
    { "id": "job3", "time_on_site": "01:00", "location": "39.653975, -105.093750" }
  ]
}

The routing_with_breaks_build.json build request with three non-relative breaks - download it here. Click here to open it in the UI.

The routing_with_breaks_build.json request produces a route with a 15 minute break at 11:00 AM, and a 30 minute break at 1:00 PM. Because the route finishes before 3:00 PM, the 15 minute route0_afternoon_break will not be routed.

Response

{
  "id": "route0_route_with_nonrelative_breaks", ...
  "stops": [
    { "type": "depot", ...  },
    { "id": "job1", "arrival_time": "09:26:58", "time_on_site": "01:00:00", ... },
    {
      "type": "break",
      "id": "route0_morning_break",
      "arrival_time": "11:00:00",
      "time_on_site": "00:15:00",
      "distance_to_meters": 0.0,
      "time_to": "00:00:00"
    },
    { "id": "job0", "arrival_time": "11:16:44", "time_on_site": "00:00:00", ... },
    { "id": "job3", "arrival_time": "11:26:12", "time_on_site": "01:00:00", ... },
    { "id": "job2", "arrival_time": "12:41:30", "time_on_site": "01:00:00", ... },
    {
      "type": "break",
      "id": "route0_lunch_break",
      "arrival_time": "13:00:00",
      "time_on_site": "00:30:00",
      "distance_to_meters": 0.0,
      "time_to": "00:00:00"
    },
    { "type": "depot", "arrival_time": "14:23:20", ... }
  ]
}

Snipped version of the response - download the full response here. Click here to open it in the UI.

The response shows that, as expected, breaks are routed at 11:00 AM and 1:00 PM.

Relative Driver Breaks

Relative breaks start at a time offset from the shift start time of the route. To use relative breaks set "breaks_relative_to_start": "true". Relative breaks can be useful with optimized shift start times as the breaks are always taken after the specified number of hours. Refer to Routing with Shifts for more information.

Request

{
  "routes": [
    {
      "id": "route0_route_with_relative_breaks",
      "location": "39.718005, -104.969531",
      "start_time": "09:00",
      "breaks": [
        { "id": "route0_morning_break", "start": "02:00", "length": "00:15" },
        { "id": "route0_lunch_break", "start": "04:00", "length": "00:30" },
        { "id": "route0_afternoon_break", "start": "06:00", "length": "00:15" }
      ],
      "breaks_relative_to_start": "true"
    }
  ],
  "jobs": [
    { "id": "job0", "location": "39.635928, -105.049219" },
    { "id": "job1", "time_on_site": "01:00", "location": "39.725375, -104.791080" },
    { "id": "job2", "time_on_site": "01:00", "location": "39.708990, -105.026954" },
    { "id": "job3", "time_on_site": "01:00", "location": "39.653975, -105.093750" }
  ]
}

The routing_with_relative_breaks_build.json build request with three non-relative break - download it here. Click here to open it in the UI.

The routing_with_relative_breaks_build.json request produces a route with a 15 minute break after two hours, and a 30 minute break after four hours. Because the route finishes in less than six hours, the 15 minute route0_afternoon_break will not be routed.

Response

{
  "id": "route0_route_with_relative_breaks", ...
  "stops": [
    { "type": "depot", ...  },
    { "id": "job1", "arrival_time": "09:26:58", "time_on_site": "01:00:00", ...  },
    {
      "type": "break",
      "id": "route0_morning_break",
      "arrival_time": "11:00:00",
      "time_on_site": "00:15:00",
      "distance_to_meters": 0.0,
      "time_to": "00:00:00"
    },
    { "id": "job0", "arrival_time": "11:16:44", "time_on_site": "00:00:00", ... },
    { "id": "job3", "arrival_time": "11:26:12", "time_on_site": "01:00:00", ... },
    { "id": "job2", "arrival_time": "12:41:30", "time_on_site": "01:00:00", ... },
    {
      "type": "break",
      "id": "route0_lunch_break",
      "arrival_time": "13:00:00",
      "time_on_site": "00:30:00",
      "distance_to_meters": 0.0,
      "time_to": "00:00:00"
    },
    { "type": "depot", "arrival_time": "14:23:20", ...  }
  ]
}

Snipped version of the response - download the full response here. Click here to open it in the UI.

The response shows that, as expected, breaks are routed after two hours at 11:00 AM, and after four hours at 1:00 PM.

Driver Break Insertion

Legal breaks are inserted with their optimal arrival time. Relative and non-relative breaks always happen at the specified break.start time. If a break occurs during a job then the break object is placed on the route_response.stops list after the job. Breaks are created only for the duration of a route. For example, if a route starts at 11:00 AM and finishes at 2:00 PM, then a 10:00AM or 3:00PM break is ignored.

An image of a route without breaks.

An image of the same route with breaks at 10:00, 11:15, and 1:15 - breaks are taken at their start time, even if this interrupts a delivery.

Driver Breaks and Over-midnight Routes

Non-relative Breaks

For non-relative breaks ("route.breaks_relative_to_start": false), breaks are repeated each day, so if a route spans midnight breaks are repeated:

An image of a non-relative break template.

An image of non-relative breaks automatically repeated each day.

{
  "id": "route0_route_with_nonrelative_breaks",
  "location": "39.718005, -104.969531",
  "breaks": [
    { "id": "route0_morning_break", "start": "04:00", "length": "00:30" },
    { "id": "route0_morning_break", "start": "07:00", "length": "00:30" },
    { "id": "route0_lunch_break", "start": "12:00", "length": "01:00" },
    { "id": "route0_afternoon_break", "start": "18:00", "length": "00:30" },
    { "id": "route0_afternoon_break", "start": "23:00", "length": "00:30" }
  ],
  "breaks_relative_to_start": "false"
}

JSON for the non-relative break template shown in the image above.

Relative Breaks

For relative breaks ("route.breaks_relative_to_start": true), breaks are instantiated based on the shift start time, and are not repeated.

An image of a relative break template.

An image of relative breaks offset to a 07:00 PM shift start time.

{
  "id": "route0_route_with_relative_breaks",
  "location": "39.718005, -104.969531",
  "breaks": [
    { "id": "route0_morning_break", "start": "04:00", "length": "00:30" },
    { "id": "route0_morning_break", "start": "07:00", "length": "00:30" },
    { "id": "route0_lunch_break", "start": "12:00", "length": "01:00" },
    { "id": "route0_afternoon_break", "start": "18:00", "length": "00:30" },
    { "id": "route0_afternoon_break", "start": "23:00", "length": "00:30" }
  ],
  "breaks_relative_to_start": "true"
}

JSON for the relative break template shown in the image above.

See Also

• The settings.enable_legal_breaks, settings.legal_break_duration and settings.legal_break_interval fields.
• The route.breaks field.
• The route.breaks_relative_to_start field.
• The stop_response.type field.
• The driver_break type.
• Routing with Shifts.