Time window properties
- Relative format of time windows
- Absolute format of time windows
- Hard and soft time windows
- Where are time windows defined
- Soft window inside a hard window
When you set a routing task, you often need to limit the order time window for order delivery, depot working hours, or a driver's shift time.
To introduce time restrictions, use the
time_window (“time window”) field in RouteQ to enter a text description of a time range.
Time windows can be set in the absolute and relative formats as described above.
Relative format of time windows
This time window format doesn't contain an absolute date and is defined as a pair of time values, for example:
07:00:00–23:00:00 for a time window that starts at 7:00 and ends at 23:00 on the current day.
For windows starting or ending on the next day (or any day in the future), the date format is specified as [D.]HH:MM – [D.]HH:MM, where D is the date shift relative to the start date of the route. For example,
07:00:00–1.03:00:00 for a time window that starts at 7:00 AM on the current day and ends at 3:00 AM the next day. Or
1.07:00:00 – 1.15:00:00 for a window that starts at 7 AM the next day and ends at 3 PM on that day.
The upper limit of the time window must always be greater than or equal to the lower limit. If you specify the window as
03:00:00, an error is thrown. This error occurs especially often when specifying windows that extend to the next day, or for windows that end at midnight. So, the window
00:00:00 will be treated as an error, you must specify
If you specify time windows without a date, the service interprets them relative to the current date and GMT+3 (Moscow) time zone or with respect to the route date specified in the
options.date field and time zone specified in the
It is important to set the route date correctly if you plan shipments on different days. In this case, the earliest planning route is indicated in the
options.date field. For example, planning is performed on 20.09, and it has shipments for the evening on 20.09 and the afternoon on 21.09. Then
2021-09-20, and for orders with shipment on the next day, September 21, the time windows should be specified in the format 1.НН:ММ – 1.НН:ММ.
The time window
23:59:59 means a round-the-clock window for the first day only. This is relevant for the depot time window: if you do planning for 2 days (the current and next day), to ensure round-the-clock operation of the depot during the planning period, specify
The example below defines the time zone for the request (Moscow time), and the time windows of the depot and orders without specifying the date. The route is built for January 20, 2019 (or the current date, if
options.date isn't specified).
Absolute format of time windows
This format contains the full date and time of the start and end of the time window in ISO 8601 format. For example,
2019-10-10T07:00:00+03:00/2019-10-10T18:00:00+03:00 for a window that starts at 7 AM Moscow time and ends at 6 PM also Moscow time.
Note that if you use the absolute time format, you can specify multiple time zones. This might be useful when you define delivery time windows at the border between time zones.
Note that when you use the absolute format of time windows, you must enter the
options.date field that defines the route date. The
options.time_zone field at the same time defines the time zone to use for the order time windows in the RouteQ response.
In the example below, the time windows for the depot, orders, and shifts are specified with the date and time zone in ISO 8601 format. The route is built for January 21, 2018, specified in each time window.
Hard and soft time windows
A time window is a restriction that must be met when building a route. For example, for an order time window, meeting the restriction means delivery within the specified time range.
You can define hard and soft time windows.
A hard time window is a restriction that must be met without any violations. If this restriction is violated when building a route, the order is completely excluded from the route and falls into the
dropped_locations field in the RouteQ response.
A soft time window is a restriction that can be violated with a penalty proportional to lateness. If this restriction is violated when creating a route, the order is not excluded from the route, but may be delivered later or earlier.
To manage hard time windows, use the
true, a hard time window is used.
false, a soft time window is used.
If you use multiple time windows, then the
hard_window parameter is defined for the entire array of windows on the same level as the
In practice, you can use soft time windows to:
Balance early or late arrivals between multiple orders if the specified number of vehicles can't deliver all orders on time.
Arrive at the depot early or return to it late, if you need to deliver all the orders within the day.
Expand the driver's shift time if early departure or late arrival is needed and allowable from the business process perspective.
When you define soft windows, penalties* apply:
- For time window violation:
penalty.out_of_time.fixed: A fixed penalty for a one-time violation of the time window.
penalty.out_of_time.minute: A penalty per minute of the time window violation.
- For early arrival:
penalty.early.fixed: A fixed penalty for early arrival.
penalty.early.minute: A penalty per minute of early arrival.
- For delays:
penalty.late.fixed: A penalty for a delay.
penalty.late.minute: A penalty per minute of delay.
* — Added to the route cost if there is a violation (
fixed) or per minute of violation (
minute). Early arrival and late arrival are the cases of violation.
If your business process does not allow for violations of time windows, we recommend the following:
Use hard time windows when initially setting the routing task.
Afterwards, use soft time windows with configurable penalties for time window violations or a soft window inside a hard window (for example, arrival 1 to 5 minutes late or early arrival may be acceptable).
Where are time windows defined
RouteQ lets you define time windows for the following entities:
locations): The allowable time of arrival at the order location.
depot): The depot's working hours, time for loading, reloading, and unloading.
Courier's shift (
vehicles.shift): Allowed shift durations.
Soft window inside a hard window
In addition to the
time_window main time window, you can set an additional (external) hard window for orders, depots, and courier shifts. It's used to limit the allowed time of a main window violation and is defined with the
hard_time_window are different parameters. The former is responsible for the strictness of the time window, and the latter is responsible for the additional time within which it is possible to violate the main time window.
The parameter has the following limitations:
The external hard window must fully include the main window specified in the
When using an external hard window, it is forbidden to specify the
If you use multiple time windows (the
time_windows parameter), then the external hard windows must meet the following requirements:
Be defined at the same level as the
Be used for each time window or not used for any.
Not overlap (same as the main time windows).
The route consists of three orders with no delay restrictions (external hard windows aren't used). The solution includes two orders without time window violations and one order (with
id = 2) with a 23-minute delay.
The same as in example 1.1, but for every order, the allowed violation of the time window is limited with the
hard_time_window parameter. The restrictions limit the delay to 10 minutes, but allow for early arrival. As a result of planning, one order is delivered on time, and the other two are delivered either earlier or with a delay that falls within the set limitations.
The route includes three orders and delivery is possible within two time windows. The
hard_time_window parameter limits the allowed violation of each of the time windows. All orders will be delivered without violations, but one order (with
id = 0) will be in the second time window.