Incorporate rest times

In the HERE Tour Planning API, you can specify the timing and duration of rest periods during a tour. Efficient scheduling of rest periods in a tour is crucial in the following aspects:

Optimization of the overall tour efficiency and driver's comfort during the tour.
Compliance with legal regulations or recommendations established by local authorities, for example, transportation agencies.

📘
Note
This feature is currently in BETA. BETA features are in end-stage development and have no major bugs but their coverage, quality, performance, or test coverage may not yet be final. The feature's data model and problem definition remain stable and unchanged from previous versions. You can use BETA features in your applications, understanding that minor behavior refinements may occur as the feature approaches full production readiness.
For more information, see Explore experimental features.

Understand rest times configuration

In the HERE Tour Planning API, you can use the restTimes object, within the fleet.types.shifts problem configuration to specify rest periods for your fleet.

📘
Note
You cannot use restTimes and breaks simultaneously within the context of a problem.

The HERE Tour Planning API distinguishes between the following types of rest periods:

driving: refers to rest breaks or periods required specifically after a specific total amount of driving time, with stops allowed in between. However, only the duration spent actively driving is counted towards this total time.
working: pertains to driving plus all other work-related activities, for example, pickup or delivery of goods.

As you define shift configuration for your fleets, you can specify the periods in which drivers rest, relax, and recuperate as either fixed breaks or restTimes. While you cannot include breaks and restTimes in a single problem simultaneously, you can mix working and breaking rest times. Including both working rest time and driving rest time simultaneously in your shift configuration can make your solution compliant with the law (if you specify intervals that reflect the local transportation regulations and the stop is scheduled at a place that permits parking) but is also optimized for driver safety and operational efficiency. You can specify the following properties for each rest period type:

type: currently, you can specify the type as fixedDuration only.
interval: specifies the frequency at which breaks should occur (in seconds).
breakDuration: specifies the break duration (in seconds).

Consider the following sample restTimes object configuration:

"restTimes": {
  "driving": {
    "type": "fixedDuration",
    "interval": 16200,
    "breakDuration": 2700
  },
  "working": {
    "type": "fixedDuration",
    "interval": 21600,
    "breakDuration": 1800
  }
}

Based on the previous example, the optimization algorithm applies rest times in the following way:

Driving rest time:
- Every 4.5 hours of driving, the driver is required to take a break solely from driving.
- This break must last exactly 45 minutes unless you specified a restTime with a longer duration.
Working rest time:
- Every 6 hours of all work-related activities (including driving), the driver is required to take a break.
- This break must last at exactly 30 minutes unless you specified a restTime with a longer duration.
  
  📘
  Note
  Because the previous example specifies another restTime that has the duration of 45 minutes, the actual length of this working restTime will be 45 minutes.

Scenario 1: Problem with a single rest time type

The following example showcases a tour planning problem for a tour comprising six jobs over an extended distance. The problem specification includes a working break every 2 hours (7200 seconds). The duration of the break is set to 30 minutes (1800 seconds).

Click to expand/collapse the sample JSON

{
  "fleet": {
    "types": [
      {
        "id": "vehicle_1",
        "profile": "normal_car",
        "costs": { "fixed": 22, "distance": 0.0002, "time": 0.0048 },
        "shifts": [
          {
            "start": {
              "time": "2023-09-20T08:09:00Z",
              "location": {
                "lat": 52.510945865670074,
                "lng": 13.393829563633428
              }
            },
            "end": {
              "time": "2023-09-20T20:09:00Z",
              "location": {
                "lat": 52.510945865670074,
                "lng": 13.393829563633428
              }
            },
            "restTimes": {
              "working": {
                "type": "fixedDuration",
                "interval": 7200,
                "breakDuration": 1800
              }
            }
          }
        ],
        "capacity": [10],
        "amount": 10
      }
    ],
    "profiles": [{ "name": "normal_car", "type": "car" }]
  },
  "plan": {
    "jobs": [
      {
        "id": "Job_1",
        "tasks": {
          "pickups": [
            {
              "places": [
                {
                  "location": {
                    "lat": 52.5063267065751,
                    "lng": 14.345924039737517
                  },
                  "duration": 180
                }
              ],
              "demand": [1]
            }
          ]
        }
      },
      {
        "id": "Job_2",
        "tasks": {
          "pickups": [
            {
              "places": [
                {
                  "location": {
                    "lat": 52.12369910922764,
                    "lng": 14.384487171627224
                  },
                  "duration": 180
                }
              ],
              "demand": [1]
            }
          ]
        }
      },
      {
        "id": "Job_3",
        "tasks": {
          "pickups": [
            {
              "places": [
                {
                  "location": {
                    "lat": 51.94851653436735,
                    "lng": 13.515333506728455
                  },
                  "duration": 180
                }
              ],
              "demand": [1]
            }
          ]
        }
      },
      {
        "id": "Job_4",
        "tasks": {
          "deliveries": [
            {
              "places": [
                {
                  "location": {
                    "lat": 52.22193780582256,
                    "lng": 13.011046397401525
                  },
                  "duration": 180
                }
              ],
              "demand": [1]
            }
          ]
        }
      },
      {
        "id": "Job_5",
        "tasks": {
          "deliveries": [
            {
              "places": [
                {
                  "location": {
                    "lat": 52.4756213511033,
                    "lng": 13.049609529291232
                  },
                  "duration": 180
                }
              ],
              "demand": [1]
            }
          ]
        }
      },
      {
        "id": "Job_6",
        "tasks": {
          "deliveries": [
            {
              "places": [
                {
                  "location": {
                    "lat": 52.44851058488946,
                    "lng": 13.384812137255604
                  },
                  "duration": 180
                }
              ],
              "demand": [1]
            }
          ]
        }
      }
    ]
  }
}

The following figure illustrates the solution to the previous problem, highlighting the working rest times occurring every two hours of work (which includes driving time with an added job duration of 180 seconds), without exceeding the break interval, as mandated by the problem specification.

📘
Note
Consider the following points for the restTimes feature, in the context of the previous and the following examples:

To achieve optimal tour planning, the algorithm might allocate break time anywhere within the working or driving intervals. Importantly, it will ensure that breaks do not occur after the designated time within the interval has elapsed.

The algorithm might schedule a rest time anywhere along the tour route.

If a working break overlaps with a job, the job extends its duration to include the working rest time.

If the driving rest time overlaps with the working rest time, the solution always displays the duration of the longer rest time.

The algorithm tends to classify breaks as working rest time when job durations are longer to prioritize ensuring sufficient rest during extended periods of work.

Scenario 2: Problem with driving and working rest times

In the provided scenario, there are two distinct types of rest times: working and driving. The working rest time consists of a 6-hour interval, while the driving rest time lasts for 4.5 hours. Within these intervals, individuals are allotted 30 minutes for rest during working periods and 45 minutes for rest during driving periods. Each job within the tour plan takes 45 minutes.

📘
Hint
To aid comprehension of driving and working periods, the job IDs in the following problem provide information on the time required to travel from the start location to each respective job location.

Click to expand/collapse the sample JSON

{
  "fleet": {
    "types": [
      {
        "id": "vehicle_1",
        "profile": "normal_truck",
        "costs": { "fixed": 22, "distance": 0.0002, "time": 0.0048 },
        "shifts": [
          {
            "start": { "time": "2023-09-20T08:00:00Z" },
            "end": {
              "time": "2023-09-22T23:00:00Z",
              "location": { "lat": 50.912724, "lng": 7.1055 }
            },
            "restTimes": {
              "working": {
                "type": "fixedDuration",
                "interval": 21600,
                "breakDuration": 1800
              },
              "driving": {
                "type": "fixedDuration",
                "interval": 16200,
                "breakDuration": 2700
              }
            }
          }
        ],
        "capacity": [10],
        "amount": 1
      }
    ],
    "profiles": [
      {
        "name": "normal_truck",
        "type": "truck",
        "traffic": { "mode": "disabled" }
      }
    ]
  },
  "plan": {
    "jobs": [
      {
        "id": "Job_1_15min_driving",
        "tasks": {
          "pickups": [
            {
              "places": [
                {
                  "location": { "lat": 48.934196, "lng": 12.687835 },
                  "duration": 2700
                }
              ],
              "demand": [1]
            }
          ]
        }
      },
      {
        "id": "Job_2_30min_driving",
        "tasks": {
          "pickups": [
            {
              "places": [
                {
                  "location": { "lat": 48.995801, "lng": 12.404328 },
                  "duration": 2700
                }
              ],
              "demand": [1]
            }
          ]
        }
      },
      {
        "id": "Job_3_1h_driving",
        "tasks": {
          "pickups": [
            {
              "places": [
                {
                  "location": { "lat": 49.066063, "lng": 11.917153 },
                  "duration": 2700
                }
              ],
              "demand": [1]
            }
          ]
        }
      },
      {
        "id": "Job_4_1h30min_driving",
        "tasks": {
          "pickups": [
            {
              "places": [
                {
                  "location": { "lat": 49.312421, "lng": 11.534065 },
                  "duration": 2700
                }
              ],
              "demand": [1]
            }
          ]
        }
      },
      {
        "id": "Job_5_2h_driving",
        "tasks": {
          "pickups": [
            {
              "places": [
                {
                  "location": { "lat": 49.526849, "lng": 11.066198 },
                  "duration": 2700
                }
              ],
              "demand": [1]
            }
          ]
        }
      },
      {
        "id": "Job_6_3h_driving",
        "tasks": {
          "pickups": [
            {
              "places": [
                {
                  "location": { "lat": 49.785296, "lng": 10.129362 },
                  "duration": 2700
                }
              ],
              "demand": [1]
            }
          ]
        }
      },
      {
        "id": "Job_7_4h_driving",
        "tasks": {
          "pickups": [
            {
              "places": [
                {
                  "location": { "lat": 49.992149, "lng": 9.153357 },
                  "duration": 2700
                }
              ],
              "demand": [1]
            }
          ]
        }
      },
      {
        "id": "Job_8_5h_driving",
        "tasks": {
          "pickups": [
            {
              "places": [
                {
                  "location": { "lat": 50.278779, "lng": 8.241558 },
                  "duration": 2700
                }
              ],
              "demand": [1]
            }
          ]
        }
      },
      {
        "id": "Job_9_6h_driving",
        "tasks": {
          "pickups": [
            {
              "places": [
                {
                  "location": { "lat": 50.672214, "lng": 7.301027 },
                  "duration": 2700
                }
              ],
              "demand": [1]
            }
          ]
        }
      }
    ]
  }
}

The following figure illustrates the resulting solution to the preceding problem:

As the visualization demonstrates, the solution to the previous problem contains both types of rest times:

driving rest time: approximately 2 hours before the interval threshold of 4.5 hours elapses
working rest time: 16 minutes before the interval threshold of 6 hours elapses

The algorithm strategically allocated these breaks with optimal spacing in terms of time to achieve maximum efficiency in the planned tour. The algorithm achieved that without exceeding the maximum limits for rest times (that is avoiding excessive driving and working periods) and keeping the number of required breaks to the necessary minimum.

📘
Note
Consider the following points for the restTimes feature, in the context of the previous example:

When both working and driving rest times are specified, the algorithm uses the longer duration for the break, regardless of which was initially scheduled. For example, if the driving rest time is 45 minutes and the working rest time is 30 minutes, the break duration will be 45 minutes when the working rest time is reached first.

When the optimization algorithm schedules a rest time, it also resets the timer for the other type of rest time. For example, if a working rest time is scheduled but by that time 2 hours of driving have also been completed, scheduling the working rest time resets the driving time counter. This prevents a new rest time from being scheduled too soon because of the driving duration.

Next steps

For more information about formulating problems in the HERE Tour Planning API, see Problem.
For an in-depth exploration of the HERE Tour Planning API methods, endpoints, and parameters, see the API Reference.