---
metadata:
  - name: generator
    content: Diplodoc Platform v5.19.6
alternate:
  - https://docs.routeq.com/doc/en/vrp/properties-of-time-window.md
title: RouteQ — time window properties
---
> **Documentation Index:** Fetch the complete configuration index at https://docs.routeq.com/doc/en/llms.txt


# 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.

You can introduce time restrictions in RouteQ with the `time_window` field where you can input 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 {#relative-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 most often occurs when specifying windows that extend to the next day, or for windows that end at midnight: for example, the window `10:00:00 – 00:00:00` will result in an error and must instead be written like `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](https://docs.routeq.com/doc/en/vrp/date-time-zone.md#date) specified in the `options.date` field and the [time zone](https://docs.routeq.com/doc/en/vrp/date-time-zone.md#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](https://docs.routeq.com/doc/en/vrp/examples-of-settings.md#simultaneous-planning-current-and-next-day-orders). 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.НН:ММ`.

{% note info %}

The time window `00:00:00 – 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 `00:00:00 – 1.23:59:59`.

{% endnote %}

**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)](https://courier.yandex.ru/vrs/api/v1/log/request/472d65e2-3f445fad-1059bbf3-e032ecb1) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/472d65e2-3f445fad-1059bbf3-e032ecb1) ⋅  [View on map](https://yandex.com/courier/mvrp-map#472d65e2-3f445fad-1059bbf3-e032ecb1)

## Absolute format of time windows {#absolute-time-windows}

This format contains the full date and time of when a window starts and ends — in ISO 8601 format. For example, `2019-10-10T07:00:00+03:00/2019-10-10T18:00:00+03:00`. This window starts at 7:00 and ends at 18:00 Moscow time (UTC+3).

To calculate penalties correctly, you can set a time window to start before the planning date, for example: `2024-10-09T18:00:00+03:00/2024-10-10T18:00:00+03:00`. This window begins on October 9, 2024, (the day before the planning date) at 18:00 UTC+3 and ends on October 10, 2024, at 18:00 UTC+3 as well. Please note that a route can't start earlier than at 00:00 on the planning date.

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 info %}

Note that when you use the absolute format of time windows, you must enter the `options.date` field that defines the [route date](https://docs.routeq.com/doc/en/vrp/date-time-zone.md#date). The `options.time_zone` field at the same time defines the [time zone](https://docs.routeq.com/doc/en/vrp/date-time-zone.md#time-zone) to use for the order time windows in the RouteQ response.

{% endnote %}

**Example**

The example below contains orders with time windows that start before the planning date and end early in the morning of the planning date. Here's an example of such a restriction: `2024-10-30T22:00:00+03:00/2024-10-31T05:00:00+03:00`. One courier works the night shift, and the other one works the morning shift. For this reason, the first courier delivers orders with the specified time windows and the second courier delivers the rest.

[API request (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/772432c8-c3bc1947-ae74a315-7e8e83af) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/772432c8-c3bc1947-ae74a315-7e8e83af) ⋅ [View on map](https://yandex.com/courier/mvrp-map#772432c8-c3bc1947-ae74a315-7e8e83af)

## Hard and soft time windows {#hard-and-soft-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.
    
{% note info %}

If you use [multiple time windows](https://docs.routeq.com/doc/en/vrp/properties-of-orders.md#order-multiple-time-windows), then the `hard_window` parameter is defined for the entire array of windows on the same level as the `time_windows` parameter.

{% endnote %}

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](#soft-inside-hard) (for example, arrival 1 to 5 minutes late or early arrival may be acceptable).
    
## Where are time windows defined {#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 {#soft-inside-hard}

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.

{% note alert %}

`hard_window` and `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.

{% endnote %}

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](https://docs.routeq.com/doc/en/vrp/properties-of-orders.md#order-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)](https://courier.yandex.ru/vrs/api/v1/log/request/73573618-34411c5b-69e9f780-d1bd9ed0) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/73573618-34411c5b-69e9f780-d1bd9ed0) ⋅ [View on map](https://yandex.com/courier/mvrp-map#73573618-34411c5b-69e9f780-d1bd9ed0)

**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)](https://courier.yandex.ru/vrs/api/v1/log/request/a5a6c8ad-333d9a1-e0a2300b-a3a44441) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/a5a6c8ad-333d9a1-e0a2300b-a3a44441) ⋅ [View on map](https://yandex.com/courier/mvrp-map#a5a6c8ad-333d9a1-e0a2300b-a3a44441)

**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)](https://courier.yandex.ru/vrs/api/v1/log/request/b6887f5c-54fdf5f8-6b4e1296-90464240) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/b6887f5c-54fdf5f8-6b4e1296-90464240) ⋅ [View on map](https://yandex.com/courier/mvrp-map#b6887f5c-54fdf5f8-6b4e1296-90464240)

{% include [warehouse-feedback](_includes/feedback-81845556eeea.md) %}