Courier working mode

By default, the service plans a route only with stops that are necessary for cargo delivery. However, couriers often can't work without stopping: they need to have lunch breaks, and you must take these into account when you build routes. Moreover, on long-distance runs, drivers are required to make stops at certain intervals to meet the work and rest requirements.

Breaks

To control the couriers' working hours, use the vehicle.rest_schedule.breaks object. You can set simple or complex schemes to schedule breaks for rest, maintenance, or other activities.

• For couriers, use the vehicles.rest_schedule.breaks object.
• For shifts, use the vehicles.shifts.N.rest_schedule.breaks object. Shift-level breaks have priority over courier-level ones.

You can specify a unique ID for each break:

• If you want to set a break at the courier level, specify the ID in the rest_schedule.breaks.N.work_break_id field on the Vehicles sheet.
• If you want to set a break at the shift level, specify the ID in the shifts.N.rest_schedule.breaks.N.work_break_id field.

IDs specified for a single schedule rest_schedule must be unique and have the same format: string or numeric.

Example 1

A courier must deliver 10 orders in two shifts. There are no shift-level breaks. There is a one-hour courier-level break (rest_duration_s = 3600) after about an hour after the start of the shift (from_start = 01:00 - 01:30).

As a result, the courier will have two breaks, one in each shift. The break in the first shift will start at 10:15 and the break in the second shift at 15:06.

API request (JSON) ⋅ API response ⋅ View on map

Example 2

A courier must deliver 15 orders in two shifts. One half-hour break (rest_duration_s = 1800) in about two hours after the start of work is scheduled for each shift. There are no courier-level breaks.

As a result, the courier will have two breaks: one for each shift. The break in the first shift will start at 11:36 and the break in the second shift at 16:30.

API request (JSON) ⋅ API response ⋅ View on map

Example 3

The same conditions as in example 2, but there's an additional one-hour break set at the courier level approximately one hour after the start of the shift (from_start = 01:00 - 01:30). As a result, breaks are set both at the shift level and at the courier level.

Consequently, only shift-level breaks at 11:07 and 16:17 are scheduled, as they have a higher priority over courier-level breaks and replace them.

API request (JSON) ⋅ API response ⋅ View on map

Break presets

You can set a courier's working hours using the parameter vehicles.rest_schedule_preset, which contains a set of settings you can use right away:

• The courier will take a 45-minute break no later than 4.5 hours of work.

• Limits will be applied to the shift duration (excluding breaks):

  • Soft: 9 hours.

  • Hard: 10 hours.

Possible values for the rest_schedule_preset parameter:

• public_transport: You can divide the break into multiple parts, each at least 10 minutes.

• private_transport: You can divide the break into two parts: 15 and 30 minutes.

• multiday_private_transport: The private_transport mode for multi-day routes. Besides regular breaks, you can also add:

  • Daily break: the last 11 hours of each weekday.
  • Weekly break: the last 45 hours of each week.

A route break will be divided into parts if the following conditions are met:

• There's not enough time between orders for a full break.

• There are waiting times between orders, where you can fit breaks.

You can also prohibit couriers from splitting breaks. To do this, use the option can_split_preset_work_breaks = false (by default it's can_split_preset_work_breaks = true).

Example 1

The courier has working hours rest_schedule_preset = private_transport. They contain a break that can be split into two parts. There's an interval between orders that a full break can fit into. As a result, a single break of 45 minutes is scheduled.

API request (JSON) ⋅ API response ⋅ View on map

Example 2

The courier has working hours rest_schedule_preset = public_transport. They contain a break that can be split into multiple parts. There's not enough time between orders for a full break. There's also a waiting time that can accommodate the part of the break. As a result, two breaks are scheduled: 21 and 23 minutes.

API request (JSON) ⋅ API response ⋅ View on map

Example 3

The courier has working hours rest_schedule_preset = public_transport. The courier has 14 orders. The shift duration has a hard restriction of 10 hours. As a result, one order remained undelivered because it would have required the courier to work more than 10 hours to deliver it.

API request (JSON) ⋅ API response ⋅ View on map

Example 4

The courier has working hours rest_schedule_preset = multiday_private_transport. They have to deliver one order to a remote location. As a result, the courier delivers the order on the following day. They start at 8:00 and make three stops along the way:

• A 45-minute break after 4 hours and 30 minutes of travel.
• An 11-hour break from the end of the workday to 8:00 the next day.
• A 45-minute break after 4 hours and 30 minutes of travel.

API request (JSON) ⋅ API response ⋅ View on map

Schedule templates

You can describe breaks for each courier separately or create templates for multiple couriers or for a shift. Moreover, you can combine individual and template schedules.

To create a template, add the template_rest_schedules parameter to options and specify an array of schedules in it: [{"id": string, "breaks": [...]}].

To use a courier-level template, add the rest_schedule_id parameter to vehicles and specify the id of the schedule template from options in that parameter. To use a shift-level template, add the mentioned parameter to vehicles.shifts.N.

Break duration

You can set the break duration using the rest_duration_s parameter mandatory for every break.

Break start conditions

The break start is indicated by a time range (from and to). If there are multiple breaks, each range specifies the working range after the end of the previous break. For example, if the first break is 04:00–05:00 and the second break is 02:00–03:00, the first break must start between 4 and 5 hours after work starts, and the second break must start between 2 and 3 hours after the end of the first break.

You can set the conditions for starting a break in several ways, which are described below.

Break place

For a courier to take a break at a specific location:

• In the type field on the Orders sheet, set the rest_place type for the location.
• In the at_rest_place field on the Vehicles sheet, set true for the break.

A unique location ID with the rest_place type is specified in the id field on the Orders sheet. Note that a location ID isn't a break ID. You can specify a unique break ID in the following fields on the Vehicles sheet:

• rest_schedule.breaks.N.work_break_id: If the break is set at the courier level.
• shifts.N.rest_schedule.breaks.N.work_break_id: If the break is set at the shift level.

The courier can't visit break locations that are situated within the geofences that are restricted for them.

You can set run-specific requirements for visiting a break location with the rest_place type using the incompatible_load_types parameter (see Order incompatibility. For example, a courier is delivering an order with the load_type = ice-cream type, and the rest_place location's type is load_type = no-refrigerator. To restrict the courier from visiting this location for a break, set ice-cream as incompatible with no-refrigerator on the Incompatible_load_types sheet.

Example

Two couriers have 19 orders scheduled for them. The first courier should rest every 2–3 hours, and the second should rest every 3–4 hours. Both couriers have the same rest location specified for them: type rest_place.

The first courier starts the route at 7:00 and arrives at the rest location at 9:09, where they rest for 30 minutes before continuing. The second courier starts the route at 8:00 and manages to deliver all of their orders before 12 without stopping to rest.

API request (JSON) ⋅ API response

Break types

Additional time intervals affect the start of the break that's set using time windows or the desired_work_duration parameter. For example, the courier should work for several hours before they can rest. To take additional time into account, specify the value of the break_type parameter.

You can set the break_type and penalty values in break schedule templates (rest_schedule.break_type, rest_schedule.penalty), as well as in the settings of each break (rest_schedule.breaks.break_type, rest_schedule.breaks.penalty).

If break_type is specified in the break schedule templates, then the break_type value in the settings of this break:

• Must be the same.
• May be not specified. In this case, the settings from the schedule templates will apply to the break.

If break_type is not specified in the schedule templates, you can set different break_type values for different breaks in their settings.

Example

A courier needs to deliver 12 orders during the shift from 09:00 to 17:00. There are two breaks.

The first break is scheduled from 11:00 to 12:00. It started two hours after the courier started his work, which corresponds to the hard time window hard_time_range = 1:30 – 3:30. The first break is planned from the start of the shift.

The second break is scheduled after the first one from 13:30 to 14:30, which also fits within the restrictions of the hard time window, hard_time_range = 1:00 - 2:00.

At the same time, the working interval between the first break and the second break matches the desired duration (desired_work_duration = 1:30) and amounts to 1 hour and 30 minutes.

API request (JSON) ⋅ API response ⋅ View on map

Order-related breaks

These break types are considered repeatable. If you specify this type once, it will be automatically added to each run.

Example

There's a route with two shifts planned: the morning and evening one. The courier's vehicle is an isothermal van. In the evenings, the courier delivers orders with temperature mode requirements.

The courier checks the temperature in the van twice a day. The following breaks are scheduled for the shifts:

• A 15-minute break before delivering the first order (before_first = 900).
• A lunch break after two hours of work (from_start = 02:00 - 02:15).
• A 15-minute break after the last order (after_last = 900).

API request (JSON) ⋅ API response ⋅ View on map

Using different break types

You can set different break types (break_type) in a single schedule. Other breaks and their duration don't affect the breaks scheduled from the start of the route (from_start) and at a specific time (exact).

Example

A courier must deliver 11 orders. There are three breaks:

• The first one lasts 15 minutes and starts after two hours of work (from_last = 02:00 - 02:15).
• The second one starts after four hours of work (from_start = 04:00 - 04:15).
• The third one is a fixed break from 14:00 to 14:20 (exact = 14:00 - 14:20).

API request (JSON) ⋅ API response ⋅ View on map

Splitting breaks

You can split the break into smaller parts if needed. For example, if there's not enough time between orders for a full break. To do this, specify the parameter can_be_split = true in the breaks schedule.

You can also specify additional parameters for the split break:

The sum of the parts of a split break can exceed its total duration.

The maximum number of parts is specified in the max_split_parts parameter. Their duration must meet the conditions:

• The first part is no less than min_first_split_part_duration_s.
• The last part is no less than min_last_split_part_duration_s.
• Each part is no less than min_split_part_duration_s.

When splitting, initial break time decreases. It may turn out that the remainder for allocating the last part of the break will be less than specified in min_last_split_part_duration_s. In this case, the minimum necessary value that's needed to comply with the min_last_split_part_duration_s restriction will be automatically added to it.

Example 1

A courier can go on one two-hour break: rest_duration_s = 7200. Several orders have narrow time windows, so you can fill the waiting time between them with breaks. Since there isn't enough time between orders for a full break, it's split into three parts.

API request (JSON) ⋅ API response ⋅ View on map

Example 2

The total break duration rest_duration_s is two hours (rest_duration_s = 7200). It's split into two parts (max_split_parts = 2). At the same time:

• min_split_part_duration_s = 2400 (40 minutes).
• min_first_split_part_duration_s = 4800 (1 hour 20 minutes).
• min_last_split_part_duration_s = 2400 (40 minutes).

The first part (1 hour 20 minutes) is split from the total break time. 40 minutes of the initial break remain. The second part (40 minutes) is split from them.

As a result, the sum of the break parts will not exceed its total duration and will amount to two hours (7200 seconds).

API request (JSON) ⋅ API response ⋅ View on map

Example 3

The same as in example 2, but the duration of the second part of the break is increased by 5 minutes (min_last_split_part_duration_s = 2700).

The first part (1 hour and 20 minutes) is split from the total break time. 40 minutes of the initial break remain. The second part must be split from the remaining 40 minutes, but min_last_split_part_duration_s = 2700 (45 minutes). The remaining time can't be negative, so the duration of the second part will be increased to 45 minutes to minimally comply with the condition min_last_split_part_duration_s = 2700.

As a result, the sum of the duration of the break parts will exceed the initially set duration by 5 minutes, amounting to 2 hours and 5 minutes (7500 seconds).

API request (JSON) ⋅ API response ⋅ View on map

Breaks during order handling

"breaks": [
  {
    "can_rest_during_service": true,
    "rest_duration_s": 3000,
    "work_time_range_from_start": "1:30 - 2:00"
  },
  ...
]    

"locations": [
  {
    "id": 123,
    "can_have_rest_during_service": true,    
    "service_duration_s": 600,  
    ...
  }
]

By default, breaks can overlap with the handling time of an order or depot. In routes, these breaks are indicated before the order or depot. The start time arrival_time_s and end time departure_time_s of the break coincide with the arrival_time_s and departure_time_s of the order or depot. Inside this overall interval, the handling time duration is determined by the parameter service_duration_s. In the response for such an order or depot, the field is_after_service_work_break = true is added to indicate that handling starts after the break.

If can_rest_during_service = true, the break can be scheduled as the first location in the shift. For regular breaks that don't overlap with the handling time, this is impossible.

To prevent breaks from overlapping with the handling time, set can_have_rest_during_service to false for the order or depot and can_rest_during_service to false for the break.

Example 1

A 50-minute break should be scheduled 1.5 hours after the start of the route. There are 2 orders in the route, with a handling time of 1 hour and the parameter can_have_rest_during_service = true. The break overlaps with the handling time for the first order, for which the courier arrives 1 hour and 8 minutes after the start of the route and leaves 2 hours and 20 minutes later.

API request (JSON) ⋅ API response ⋅ View on map

Example 2

The same as in example 1, but orders have the parameter can_have_rest_during_service = false. The break is scheduled at the first order's location, but before handling the order and too early: just 1 hour and 9 minutes after the start of the route.

API request (JSON) ⋅ API response ⋅ View on map

Break chains

The rest_schedule can contain many independent breaks break chains. Each chain can contain many breaks with special conditions. The start of a break in every chain depends only on the built route. It doesn't depend on breaks in other chains.

The order of chains doesn't matter, but you must specify breaks in one chain sequentially.

If the route is completed before the stop (for example, the route is completed in 3 hours, and the stop is scheduled after 4 hours), all the unmade stops are reset.

Example

The route is built with 30-minute rest breaks after 4–4.5 hours of work. 15 hours after the start of the route, a sleep break is planned. As a result, a sleep break is scheduled 1.5 hours after a rest break.

API request (JSON) ⋅ API response ⋅ View on map

Penalties

In some cases, RouteQ can plan routes that violate the rest window. To apply penalties for such violations, use the fields penalty.late and penalty.early. If the penalty is higher than the savings resulting from the window violation, the route is planned without violations.

Repeat conditions

Example 1

The courier delivers orders to a neighboring city and periodic breaks. Breaks are set every 60–80 minutes of the route (travel_time_range) using the repeat condition repeatable. As a result, the algorithm scheduled two breaks.

API request (JSON) ⋅ API response ⋅ View on map

Example 2

Same as in example 1, but the route extends over several days, with sleep breaks scheduled every 12 hours:

• The repeat condition repeatable is used.

• The minimum and maximum route duration before rest travel_time_range: "12:00–12:00".

API request (JSON) ⋅ API response ⋅ View on map

Example 3

A courier delivers orders containing chemicals, so they need to take a 30-minute break every two hours.

As a result, three breaks are scheduled:

• Two breaks lasting 30 minutes every two hours of the route set with the repeatable condition (hard_time_range).

• One-hour lunch break.

API request (JSON) ⋅ API response ⋅ View on map