Time window properties

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 [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 on the current day and ends at 3:00 the next day. Or 1.07:00:00 – 1.15:00:00 for a window that starts at 7:00 the next day and ends at 15:00 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 07:00:00 – 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 10:00:00 – 00:00:00 will be treated as an error, you must specify 10:00:00 – 1.00:00:00.

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 options.time_zone field.

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 options.date = 2021-09-20, and for orders with shipment on the next day (that is September 21) the time windows should be specified as 1.НН:ММ – 1.НН:ММ.

Example

The example below defines the time zone for the request (UTC+3), 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).

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

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:00 and ends at 18:00 UTC+3.

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.

Example

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.

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

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 hard_window field:

• If true, a hard time window is used.

• If false, a soft time window is used.

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.

Penalties are 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:

• Orders (locations): The allowable time of arrival at the order location.

• Depot (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 parameter.

The parameter has the following limitations:

• The external hard window must fully include the main window specified in the time_window parameter.

• When using an external hard window, it is forbidden to specify the hard_window parameter.

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 time_window child parameter.

• Be used for each time window or not used for any.

• Not overlap (same as the main time windows).

Example 1.1

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.

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

Example 1.2

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.

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

Example 2

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.

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

Contact support