---
metadata:
- name: generator
content: Diplodoc Platform v5.19.6
alternate:
- https://docs.routeq.com/doc/en/vrp/properties-of-vehicles-routes.md
- https://docs.routeq.com/doc/tr/vrp/properties-of-vehicles-routes.md
title: RouteQ — vehicle properties — routes, runs, shifts
---
> **Documentation Index:** Fetch the complete configuration index at https://docs.routeq.com/doc/en/llms.txt
# Courier shifts and routes
With vehicle properties, you can configure [courier shifts](#shifts), their [maximum duration](#shift-duration), the [number of runs](#vehicle-max-runs) and [stops](#shift-stops), set the [maximum mileage](#shift-mileage), and specify [restrictions for routes](#route-proximity).
## Vehicle or courier shifts {#shifts}
You can define one or more work shifts for a vehicle. Use the `vehicle.shifts` field to define the shifts.
A shift is a time range when the vehicle is allowed to operate. Shift time includes the loading time at the depot, travel time, and handling time at order locations, as well as unloading time at the depot (if the vehicle returns to the depot).
To use one or more shifts in Excel, define the following fields:
- `shifts.0.time_window`: A [soft time window](https://docs.routeq.com/doc/en/vrp/properties-of-time-window.md) corresponding to the vehicle's operating hours.
- `shifts.0.hard_window`: Flag indicating a [hard time window](https://docs.routeq.com/doc/en/vrp/properties-of-time-window.md#hard-and-soft-windows). If the time window is hard, the algorithm can't go outside the specified interval.
- `shifts.0.service_duration_s`: Time between shifts (in seconds). For example, it can be the time needed to replace the driver or exchange documents.
You can also restrict the [maximum shift duration](#shift-duration) (`shifts.N.max_duration_s` and `shifts.N.hard_max_duration_s`).
In the case of a **soft** time window, you can set additional penalties:
- For time window violation:
- `shifts.0.penalty.out_of_time.fixed`: A fixed penalty for one-time violation of the shift's time window.
- `shifts.0.penalty.out_of_time.minute`: A penalty per minute of the shift's time window violation.
- For early departure:
- `shifts.0.penalty.early.fixed`: A fixed penalty for one-time start of work before the shift's time window.
- `shifts.0.penalty.early.minute`: A penalty per minute of work start before the shift's time window.
- For late arrival:
- `shifts.0.penalty.late.fixed`: A fixed penalty for one-time work completion later than the shift's time window.
- `shifts.0.penalty.late.minute`: A penalty per minute of work end after the shift's time window.
To limit permissible violations of the shift's time window, you can set a [hard window around a soft one](https://docs.routeq.com/doc/en/vrp/properties-of-time-window.md#soft-inside-hard).
### Start, end, and duration of shift {#start-duration-end}
Let's say a shift's `time_window` is from 9:00 to 18:00. The properties used are hard time window (`hard_window`), maximum shift duration (`max_duration_s`), and [flexible start time from the depot](https://docs.routeq.com/doc/en/vrp/properties-of-depot.md#depot-flexible-start-time) (`depot.flexible_start_time`).
#|
|| **How to plan courier's work** | **Parameters** ||
||
Set a work interval that will **preferably** last no longer than 6 hours, **strictly** between 9:00 and 18:00
|
`hard_window` = `true`
`max_duration_s` = 6 hours (less than the shift window)
`flexible_start_time` = `true` ||
||
Start the work **strictly** at 9:00, **preferably** end it before 15:00 and **strictly** not later than 18:00 (this parameter combination corresponds to `time_window` = `9:00 – 15:00`, `hard_time_window` = `9:00 – 18:00`, `flexible_start_time` = `false`)
|
`hard_window` = `true`
`max_duration_s` = 6 hours (less than the shift window)
`flexible_start_time` = `false` ||
||
Set a work interval that will **preferably** last no longer than 6 hours, **preferably** between 9:00 and 18:00
|
`hard_window` = `false`
`max_duration_s` = 6 hours (less than the shift window)
`flexible_start_time` = `true` ||
||
Start the work **strictly** at 9:00, **preferably** end it before 15:00 and **preferably** not later than 18:00 (this parameter combination corresponds to `time_window` = `9:00 - 15:00`, `max_duration_s` = 9 hours)
|
`hard_window` = `false`
`max_duration_s` = 6 hours (less than the shift window)
`flexible_start_time` = `false` ||
||
You **may** start work later than 9:00, finish **preferably** before 18:00, **preferably** work no longer than 10 hours
|
`hard_window` = `false`
`max_duration_s` = 10 hours (more than the shift window)
`flexible_start_time` = `true`||
||
Start the work **strictly** at 9:00, finish **preferably** before 18:00, but **preferably** no later than 19:00 (this combination of parameters corresponds to `time_window` = `9:00 – 19:00`, `max_duration_s` = 9 hours)
|
`hard_window` = `false`
`max_duration_s` = 10 hours (more than the shift window)
`flexible_start_time` = `false` ||
||
With this combination of parameters, you won't be able to plan the solution
|
`hard_window` = `true`
`max_duration_s` = 10 hours (more than the shift window)
`flexible_start_time` = `true` or `flexible_start_time` = `false` ||
|#
{% endcut %}
{% note info %}
Note that to define multiple shifts, you need multiple Excel fields with an increasing numeric index.
For example. `shifts.0.time_window` refers to the first shift, and `shifts.1.time_window` refers to the second one.
{% endnote %}
**Example**
The request to RouteQ includes one vehicle with three shifts (morning, afternoon, and evening) and three orders, of which one order has a delivery time in the morning, and two others in the evening.
{% note info %}
Note that the RouteQ response will only use the morning and evening shifts, since there are no delivery orders for the day shift.
{% endnote %}
[API request (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/5b30b1fe-ec08f161-91823f6c-83d6a609) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/5b30b1fe-ec08f161-91823f6c-83d6a609) ⋅ [View on map](https://yandex.com/courier/mvrp-map#5b30b1fe-ec08f161-91823f6c-83d6a609)
## Multiple courier runs per day {#vehicle-max-runs}
By default, a courier starts and ends their route at a depot, that is they complete exactly one route during a working day (shift).
If a courier can return to the depot anytime during the work shift to reload additional orders, you can limit the number of runs using one of the parameters:
- `vehicle.shifts.N.max_runs`: The maximum number of runs per shift. The default is 1.
- `vehicle.max_runs`: The maximum number of runs for all the courier's shifts summed up (for example, the courier can perform all the runs in one shift). The number of courier runs can be lower than the number of shifts. The default is 1.
- If none of the parameters are specified, the courier can make as many runs as they have shifts (one run per shift).
{% note info %}
You can use `vehicle.max_runs` or `vehicle.shifts.N.max_runs` in the planning task, but not both parameters at the same time.
At least one shift should be set for the courier.
{% endnote %}
**Example**
The example below uses one vehicle with the limited carrying capacity of 2 tons and three orders with a weight of 0.8 tons. The vehicle is allowed to do two runs. This means that after completing two orders, the vehicle can return to the depot to pick up and deliver another order.
[API request (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/fedcdbb9-4bc2bf4f-fa971929-b981b7d) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/fedcdbb9-4bc2bf4f-fa971929-b981b7d) ⋅ [View on map](https://yandex.com/courier/mvrp-map#fedcdbb9-4bc2bf4f-fa971929-b981b7d)
### Break before the last run {#rest-between-runs}
The break is set using the `vehicle.extra_wait_before_last_run_s` object. Mind the following:
- The break is scheduled before the last run in the shift.
- The start of the last run is shifted by the specified break time.
#|
||**Parameter** | **Value** | **Example**||
||`extra_wait_before_last_run_s` | Break duration in seconds. | `"extra_wait_before_last_run_s": 2700`
Break time is 45 minutes (2700 seconds).||
|#
**Example**
A courier has two scheduled runs. A one-hour break and a 45-minute break are scheduled between these runs (`extra_wait_before_last_run_s` = 2700).
As a result, two breaks are scheduled:
- 60 minutes in the first run.
- 45 minutes before the start of the second run. As a result, the second run starts 45 minutes later.
[API request (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/ac45d92-4f470ec1-5f39ad60-20c7e4f5) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/ac45d92-4f470ec1-5f39ad60-20c7e4f5) ⋅ [View on map](https://yandex.com/courier/mvrp-map#ac45d92-4f470ec1-5f39ad60-20c7e4f5)
## Limit the number of stops per shift {#shift-stops}
When planning a route, you can specify the minimum and maximum number of stops in the route. This can be useful, for example, to limit the maximum courier workload per day or, on the contrary, make sure that the courier gets on the route with a certain minimum number of stops.
For this, RouteQ uses the `minimal_stops` and `maximal_stops` shift parameters. You can set the number of stops for each courier.
The restriction is not strict and may be violated. If the limit on the minimum number of stops is violated, a penalty applies. The penalty is specified in the following shift fields: `penalty.stop_lack.fixed` (for making fewer stops than the minimum number) and `penalty.stop_lack.per_stop` (for each stop missing under the minimum number).
In the same way, if the limit on the maximum number of stops is violated, a penalty applies. The penalty is specified in the following shift fields: `penalty.stop_excess.fixed` (for making more stops than the maximum number) and `penalty.stop_excess.per_stop` (for each stop above the maximum number).
{% note info %}
Usually when you restrict the number of stops, the solution metrics degrade since the solution favors restrictions at the cost of the optimal route.
{% endnote %}
### Unique stops {#minimal-unique-stops}
When using the `minimal_stops` parameter, orders with matching coordinates are considered different stops if they aren't consecutive in the route. For the `minimal_stops` condition to be fulfilled, the algorithm may plan the route to have the courier visit the same address multiple times.
To avoid repeat visits, use the `minimal_unique_stops` parameter and `penalty.unique_stop_lack.fixed` and `penalty.unique_stop_lack.per_stop` penalties instead of `minimal_stops`.
The `minimal_unique_stops` parameter considers only orders with unique coordinates, so there won't be any repeat visits planned for the courier. However, orders to the same address may be assigned to different couriers, because such stops are considered different in this case, and the algorithm can use this to enforce the `minimal_unique_stops` limit.
It makes sense to use the `minimal_unique_stops` limit if the route has a lot of multi-orders.
### Stops for non-active couriers {#ignore-min-stops-for-unused}
By default, the `minimal_stops` and `minimal_unique_stops` limits apply to all assigned couriers. When you specify more couriers than necessary, and the `penalty.stop_lack` or `penalty.unique_stop_lack` penalty value is too high, this can result in suboptimal planning.
To set the minimum number of stops in a shift and build an effective route at the same time, use the option `ignore_min_stops_for_unused` (see [Counting the minimum number of stops for active vehicles only](https://docs.routeq.com/doc/en/vrp/optimization-count.md)).
**Example 1**
In the example, the route is built for 3 couriers who deliver to 15 points. Since there are no restrictions for the route, the route is built the usual way.
[API request (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/11838b12-e031f2fa-580da0a2-c972bf41) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/11838b12-e031f2fa-580da0a2-c972bf41) ⋅ [View on map](https://yandex.com/courier/mvrp-map#11838b12-e031f2fa-580da0a2-c972bf41)
**Example 2**
This example has the same conditions as example 1, but sets the limit of 4 minimum stops per courier. As a result, the routes changed so that each courier visited at least 4 delivery locations.
[API request (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/b047dde9-68385061-f63d36a1-d4fee317) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/b047dde9-68385061-f63d36a1-d4fee317) ⋅ [View on map](https://yandex.com/courier/mvrp-map#b047dde9-68385061-f63d36a1-d4fee317)
**Example 3**
This example has the same conditions as example 1, but sets the limit of 5 maximum stops per courier. As a result, orders are distributed evenly among all couriers, even though several orders are located next to each other and can be completed by one courier.
[API request (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/350b1d5e-3f98f16c-5fecb6db-463afe14) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/350b1d5e-3f98f16c-5fecb6db-463afe14) ⋅ [View on map](https://yandex.com/courier/mvrp-map#350b1d5e-3f98f16c-5fecb6db-463afe14)
## Maximum shift duration {#shift-duration}
Sometimes you may need to extend the courier's working hours. But you also need to limit the maximum shift length and set the window you want to fit into. For example, there's a specific 14-hour time window during which couriers can make deliveries: from 8:00 to 22:00. However, the duration of each courier's shift must not exceed 10 hours (`max_duration_s`), and there should be no more than 8 working hours per shift (`max_working_duration_s`).
RouteQ helps you schedule shifts with hard time windows and preferred lengths. In this case, the courier's shift length doesn't affect the work start time. It only affects the time that they spend completing orders.
The maximum shift length can be set as a soft restriction `shifts.N.max_duration_s` that can be violated for a penalty or as a hard restriction `shifts.N.hard_max_duration_s` that can't be violated:
- When planning with a soft restriction, the workload that doesn't fit into one courier's preferred shift is distributed among others or to the same courier, but with penalties for violating the shift length. All orders that can't be completed in `max_duration_s` are added to the route with the penalty specified in the `shift.penalty.late` field (if applicable) or in the `shift.penalty.out_of_time` field all other times. The total route penalty for violating the maximum shift length is shown in the API response in the `overtime_penalty` field. If the estimated order cost including penalties is higher than the cost of completing the order by another courier, the order is handed over to another courier.
- When planning with a hard restriction, the courier's shift never exceeds the `hard_max_duration_s` value.
The maximum working time per shift can also be defined by a soft restriction `shifts.N.max_working_duration_s` or hard restriction `shifts.N.hard_max_working_duration_s`.
- If the courier violates a soft restriction, the workload is redistributed to other couriers or given back to the same courier, but with penalties. Orders that are not completed within the shift's working time `max_working_duration_s` will be added to the route with a penalty `working_overtime`:
- `shifts.N.penalty.working_overtime.fixed`: Penalty for exceeding the maximum working time per shift.
- `shifts.N.penalty.working_overtime.minute`: Penalty for each minute of such overtime.
If the penalty value isn't specified, the penalty for violating the time window `shift.penalty.out_of_time` will be applied to the orders. You can find the total penalty amount in the `working_overtime_penalty` field of the API response. The order will be transferred to another courier if the estimated cost of the order (including penalties) exceeds the cost of completing the order with another courier.
- When planning with a hard restriction, the maximum duration of working time per shift never exceeds the value specified in `hard_max_working_duration_s`.
If you use both soft and hard restrictions for `max_duration_s` and `max_working_duration_s`, the hard one can't be lower than the soft one. By default, `max_duration_s` and `max_working_duration_s` are set to 2 days, while `hard_max_duration_s` and `hard_max_working_duration_s` are set to 30 days.
**Example 1**
Let's say the shift window `shifts.N.time_window` is from 8:00 to 23:00. By default, routes will be built to use the minimum number of couriers.
If you specify `max_duration_s` = 14400, the load is distributed between couriers, and each of them works for approximately 4 hours (the shift length is set in seconds). Some couriers may still work more than 4 hours, because it's less costly to pay for extra hours than to hand over the order to another courier.
As a result of planning, orders are distributed among three couriers. One courier's shift went over 4 hours. The penalty amount is shown in the API response in the `overtime_penalty` field.
[API request (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/df538b6f-fcfdef29-905bfff2-2026c242) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/df538b6f-fcfdef29-905bfff2-2026c242) ⋅ [View on map](https://yandex.com/courier/mvrp-map#df538b6f-fcfdef29-905bfff2-2026c242)
**Example 2**
The same as in Example 1, but with hard restrictions on the maximum shift length: `hard_max_duration_s` = 14400. When planning, all couriers are given shifts that are 4 hours or less. As a result, the number of couriers increased to 4.
[API request (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/c128465f-b5b6183a-742a5ecb-c487b20f) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/c128465f-b5b6183a-742a5ecb-c487b20f) ⋅ [View on map](https://yandex.com/courier/mvrp-map#c128465f-b5b6183a-742a5ecb-c487b20f)
**Example 3**
Three couriers are delivering 26 orders. The shift window `shifts.N.time_window` is 8:00 to 23:00. Penalties are set for exceeding the maximum working time per shift: `shifts.N.penalty.working_overtime.fixed` for overtime, and `shifts.N.penalty.working_overtime.minute` for overtime per minute.
If you specify `shifts.0.max_working_duration_s` = 14,400, each courier will work for approximately 4 hours. The restriction is soft, and one courier worked overtime.
As a result of the planning, all orders are distributed among couriers, and the total penalty amount for overtime is indicated in the field `working_overtime_penalty` of the API response.
[API request (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/52de0997-7584e652-2b690f8b-d6aae033) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/52de0997-7584e652-2b690f8b-d6aae033) ⋅ [View on map](https://yandex.com/courier/mvrp-map#52de0997-7584e652-2b690f8b-d6aae033)
**Example 4**
Same as in Example 3, but with a hard restriction on the maximum working time per shift `shifts.N.hard_max_working_duration_s` = 14,400.
As a result of planning, all couriers are busy and work for a maximum of 4 hours. However, one of the orders remains unassigned.
[API request (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/19c4f69-d64c6dc4-b1ec98f3-e9269ef5) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/19c4f69-d64c6dc4-b1ec98f3-e9269ef5) ⋅ [View on map](https://yandex.com/courier/mvrp-map#19c4f69-d64c6dc4-b1ec98f3-e9269ef5)
## Maximum mileage per shift {#shift-mileage}
In some cases, you need to limit the mileage per vehicle. For example:
- The planning includes hired cars, and their rate implies limited mileage.
- You can assign specific vehicles for far-away points. Then you can limit the mileage for other vehicles.
The `shifts.max_mileage_km` parameter determines the maximum vehicle mileage per shift. The entire mileage is taken into account, including:
- Traveling from the depot or starting point to the first point from the order list.
- Returning to the depot or end point of the route from the last point in the order list.
The restriction is soft: the algorithm may violate it. Penalties are set in the fields:
- `shifts.penalty.max_mileage.fixed`: A fixed penalty for exceeding the maximum mileage (1000 by default).
- `shifts.penalty.max_mileage.km`: A penalty per each kilometer in excess of the maximum mileage (100 by default).
If the maximum mileage per run is critical to you, and the vehicle can do several runs per shift, you can create multiple identical shifts (see **Example 2**).
If the courier uses [public transit](#routing-mode), only the walking part of the route is returned as the mileage.
**Example 1**
The mileage limit per courier is 50 km, with a big penalty for violating this restriction. In the result, the planned mileage on any route doesn't exceed 50 km.
[API request (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/2baffdf7-e330bef-9c22aa4c-13af933c) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/2baffdf7-e330bef-9c22aa4c-13af933c) ⋅ [View on map](https://yandex.com/courier/mvrp-map#2baffdf7-e330bef-9c22aa4c-13af933c)
**Example 2**
There's one courier and each of their runs should be no more than 50 km. To achieve this, the courier has several shifts with the same time windows and mileage restrictions. The result includes 3 routes, each one less than 50 km long.
[API request (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/6852b43a-d2b1c520-28f07322-9515b082) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/6852b43a-d2b1c520-28f07322-9515b082) ⋅ [View on map](https://yandex.com/courier/mvrp-map#6852b43a-d2b1c520-28f07322-9515b082)
## Limit the mileage and number of stops per run {#ride-limitations}
Sometimes you might need to restrict the mileage and number of stops for a specific run in the route.
To set a mileage limit, go to the **Vehicles** sheet and specify the maximum allowed mileage per run in kilometers in the `shifts.N.run_restrictions.max_mileage_km.value` field. If necessary, add penalties for exceeding the limit using the following fields:
* `shifts.N.run_restrictions.max_mileage_km.penalty.fixed`: The penalty for exceeding the maximum mileage (defaults to 1000).
* `shifts.N.run_restrictions.max_mileage_km.penalty.km`: The penalty for each kilometer in excess of the maximum mileage (defaults to 100).
To limit the number of stops in the run, specify values for the following parameters on the **Vehicles** sheet:
* `shifts.N.run_restrictions.maximal_stops.value`: The maximum number of stops.
* `shifts.N.run_restrictions.minimal_stops.value`: The minimum number of stops.
Penalties can be imposed for violating the limit on the number of stops. If necessary, specify penalty values in the following fields:
* `shifts.N.run_restrictions.maximal_stops.penalty.fixed`: The penalty for exceeding the maximum number of stops (defaults to 1000).
* `shifts.N.run_restrictions.maximal_stops.penalty.per_stop`: The penalty for each extra stop (defaults to 100).
* `shifts.N.run_restrictions.minimal_stops.penalty.fixed`: The penalty for violating the minimum number of stops (defaults to 1000).
* `shifts.N.run_restrictions.minimal_stops.penalty.per_stop`: The penalty for each missing stop (defaults to 100).
**Example 1**
A courier must deliver 10 orders. There are no restrictions on the mileage and number of stops in the run.
As a result, the courier delivers all the orders in 1 run.
[API request (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/663e15c2-ad3b513-2158b7c2-18169e3f) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/663e15c2-ad3b513-2158b7c2-18169e3f) ⋅ [View on map](https://yandex.com/courier/mvrp-map#663e15c2-ad3b513-2158b7c2-18169e3f)
**Example 2**
Same as example 1 except for the first shift runs, where the following restrictions on the maximum number of stops are set:
* `shifts.0.run_restrictions.maximal_stops.value` = 1
* `shifts.0.run_restrictions.maximal_stops.penalty.fixed` = 1 000 000
* `shifts.0.run_restrictions.maximal_stops.penalty.per_stop` = 1 000
The penalties are so high that it's unprofitable to violate the stop restrictions. As a result, the courier delivers the orders in 2 runs. In the first run they deliver order 8, and in the second run they deliver all the remaining orders.
[API request (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/e09509eb-3bb43c5c-c01ca72f-ebabf72c) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/e09509eb-3bb43c5c-c01ca72f-ebabf72c) ⋅ [View on map](https://yandex.com/courier/mvrp-map#e09509eb-3bb43c5c-c01ca72f-ebabf72c)
**Example 3**
Same as example 2 except for the first shift runs, where the penalties for exceeding the maximum number of stops (`shifts.0.run_restrictions.maximal_stops.penalty.fixed` and `shifts.0.run_restrictions.maximal_stops.penalty.per_stop`) are no longer used. The run has the following restriction: `shifts.0.run_restrictions.maximal_stops.value` = 1.
Plus, the cost of one run (3000) is added to the `cost.run` field.
As a result, the courier delivers all the orders in 1 run. Under the given conditions, it's more profitable to violate the restriction and get a penalty than to split the orders into several runs. The penalty amount is 1100, where 1000 is the default value for `shifts.0.run_restrictions.maximal_stops.penalty.fixed` and 100 is the default value for `shifts.0.run_restrictions.maximal_stops.penalty.per_stop`.
[API request (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/dc8f087b-affae9dc-4f0170df-473390d9) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/dc8f087b-affae9dc-4f0170df-473390d9) ⋅ [View on map](https://yandex.com/courier/mvrp-map#dc8f087b-affae9dc-4f0170df-473390d9)
## Route density {#route-proximity}
To set the preferred area of work for a vehicle so that the route includes orders near a certain location, use the `global_proximity_attraction_point` parameter. In the parameter value, specify the location `id` with the `garage` type. This is used as a hotspot: the algorithm aims to reduce the total distance between orders on the route and this location.
The density of routes around the hotspot is determined by the `options.global_proximity_factor` option: the greater its value, the denser the routes are. For more information about this option, see [Dense routes](https://docs.routeq.com/doc/en/vrp/grouping-routes.md).
The maximum distance from the route locations to the hotspot is stored in the `max_distance_to_attraction_point_m` parameter, which can be used to calculate the [cost of the route](#max-distance-to-attraction-point-m). The total sum of distances from all orders to the hotspot on the route affects the penalty for inadequate route grouping.
{% cut "Other ways to group orders geographically" %}
- You can use the `global_proximity_factor` option to build [dense routes](https://docs.routeq.com/doc/en/vrp/grouping-routes.md) without setting a “hotspot”. This option only works for vehicles that don't have the `global_proximity_attraction_point` parameter set.
- By using [geofences](#geozones) for vehicles, you can set restrictions on delivery zones. While geofence restriction can't be violated, route density settings are a more flexible tool.
{% endcut %}
**Example 1**
Three vehicles have to deliver 15 orders. The route is calculated based on the order weight and vehicle capacity. There are no other restrictions on the route.
[API request (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/9b6d127d-4c840689-4c039f34-33581bc2) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/9b6d127d-4c840689-4c039f34-33581bc2) ⋅ [View on map](https://yandex.com/courier/mvrp-map#9b6d127d-4c840689-4c039f34-33581bc2)
**Example 2**
The same as in example 1, but each courier has a set hotspot that shows their preferred area of work. As a result, the routes are more dense. The maximum distance from the order to the hotspot on the route is 20,663 m.
[API request (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/afea8c56-ac603463-5c6bc57a-fb1c0878) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/afea8c56-ac603463-5c6bc57a-fb1c0878) ⋅ [View on map](https://yandex.com/courier/mvrp-map#afea8c56-ac603463-5c6bc57a-fb1c0878)
**Example 3**
The same as in example 2, but one of the couriers has a different hotspot. Because orders are regrouped, the location of routes on the map has changed. The maximum distance from the order to the hotspot increased to 28,528 m.
[API request (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/80ce390a-e5c3ed62-3ea846c2-e2aaa95) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/80ce390a-e5c3ed62-3ea846c2-e2aaa95) ⋅ [View on map](https://yandex.com/courier/mvrp-map#80ce390a-e5c3ed62-3ea846c2-e2aaa95)
## Planned route {#planned-route}
The user can specify which courier should deliver particular orders. This is useful:
- For [additional planning](https://docs.routeq.com/doc/en/vrp/additional-planning.md) when you have pre-planned routes.
- When the order requires a specific courier.
To specify pre-planned orders for the courier, use the `vehicle.planned_route` option. This option has the following properties:
- When planning, all orders that you specify in `vehicle.planned_route` can't become unassigned, even if strict restrictions are violated, such as vehicle capacity or time windows for which `hard_window` = `true`.
- By default, the order sequence set in `planned_route` isn't fixed. When re-planning, orders can be arranged in a new sequence.
- If you need to save the route that's specified in `planned_route` without saving changes (sequence changes and adding new orders), use `vehicle.fixed_planned_route` = `true`.
For each order in `planned_route`, be sure to specify the vehicle shift (even if the vehicle only has 1 shift).
If in `planned_route` several shifts are specified, you can lock orders for shifts using the `fix_planned_shifts` = `true` option. By default, the value is `false`.
If a courier arrives too early, delivery time of the order is determined by the `vehicle.wait_if_early` parameter:
- `true`: The courier waits for the order time window to start (default value).
- `false`: The courier handles the order as soon as they arrive.
{% note alert %}
If there is only a hard time window `location.hard_window` = `true` for an order, the `vehicle.wait_if_early` parameter with the `false` value won't affect the order delivery.
{% endnote %}
If the courier needs to visit [depots for reloading](#visit-additional-depot) while following the route, specify them in the `middle_depot_id` field. They may be the same as the depots the courier visits at the start or at the end of the route.
If the courier needs to visit depots for reloading in `planned_route`, set `is_middle_depot` = `true` (it's `false` by default). If you set `is_middle_depot` = `true` for all depots, the algorithm will plan the start and end depots based on the courier settings (see sections [Start from one of multiple depots](https://docs.routeq.com/doc/en/vrp/properties-of-vehicles-depot.md#start-from-any) and [Returning to a depot at the end of the route or run](https://docs.routeq.com/doc/en/vrp/properties-of-vehicles-depot.md#return-to-depot)).
**Example 1**
Both couriers had pre-planned orders in `planned_route`. As a result, these orders were given to these two couriers.
[API request (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/6aa1d440-bff2d49-b86afbee-1900f44f) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/6aa1d440-bff2d49-b86afbee-1900f44f) ⋅ [View on map](https://yandex.com/courier/mvrp-map#6aa1d440-bff2d49-b86afbee-1900f44f)
**Example 2**
This example involves 1 vehicle that has orders linked to it via `planned_route`. The total weight of the orders exceeds the vehicle capacity, but the route is still being planned (because orders specified in this option can't be unallocated). But the ask status is `UNFEASIBLE`.
[API request (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/bbdfd67f-24b1190e-3e0a9aed-9b9ded7b) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/bbdfd67f-24b1190e-3e0a9aed-9b9ded7b) ⋅ [View on map](https://yandex.com/courier/mvrp-map#bbdfd67f-24b1190e-3e0a9aed-9b9ded7b)
**Example 3**
Theoretically, 2 couriers could deliver all 20 orders without overload and without being late. But a fixed sequence is specified for courier 1 using the `vehicle.fixed_planned_route` = `true` parameter, so they'll only deliver orders from this sequence. Courier 2 isn't limited by a strict plan, so they'll take as many orders as they can carry. Several orders will remain in the depot, despite the fact that courier 1 has the space and time.
[API request (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/a838532d-b63f0770-34e8ca86-52241b38) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/a838532d-b63f0770-34e8ca86-52241b38) ⋅ [View on map](https://yandex.com/courier/mvrp-map#a838532d-b63f0770-34e8ca86-52241b38)
**Example 4.1**
2 couriers need to deliver 15 orders in 2 shifts. Using the `planned_route` option, orders 1-8 are assigned to courier 1, and orders 9-15 to courier 2. At the same time, it's indicated that orders 1-4 and 9-12 must be delivered during the first shift, and orders 5-8 and 13-15 during the second shift. Since `fix_planned_shifts` = `false` and couriers manage to deliver all orders within one shift, the distribution of orders by shifts is not taken into account.
[API request (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/89cf9a98-4114ebbc-306feb86-d051a8b) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/89cf9a98-4114ebbc-306feb86-d051a8b) ⋅ [View on map](https://yandex.com/courier/mvrp-map#89cf9a98-4114ebbc-306feb86-d051a8b)
**Example 4.2**
The conditions are the same as in example 4.1, but the option `fix_planned_shifts` = `true`. This means the shifts during which orders have to be delivered are taken into account.
[API request (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/f4927523-de7e2964-84a36f34-1d0e823d) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/f4927523-de7e2964-84a36f34-1d0e823d) ⋅ [View on map](https://yandex.com/courier/mvrp-map#f4927523-de7e2964-84a36f34-1d0e823d)
## Fixed part of the route {#visited-locations}
The `visited_locations` feature is useful if:
- The beginning of route must follow a particular path.
- You need to change the start point when doing [additional planning](https://docs.routeq.com/doc/en/vrp/additional-planning.md).
The route must be fixed for each courier individually.
To do this, specify the `visited_locations` array in `vehicles` and describe the points of the fixed route using the following parameters.
#|
||**Parameter** | **Description**||
||`id`* | Order ID from `locations` or depot ID from `depots`. Please note that the order and depot IDs must be different.||
||`shift_id` | ID of the courier shift from `vehicle.shifts`. Determines the shift in which to serve this point.||
||`time` | The time of departure from the point. If the first point of a fixed part of the route:
- Has a specified time, that's the starting point.
- Has no specified time, the route starts from the depot, and the start of work is calculated according to the depot or shift window.
You can specify this parameter for several orders, so that the visit time is calculated according to the time specified in `time`.||
||`wait_if_early` | The need to wait for the start of the time window in case of early arrival.
- Its default value is`true`, meaning that the courier will wait for the start of the time window.
- If you specify `false`, the courier will start service immediately after arrival.||
|#
\* Required parameter
**Example 1**
There are 5 orders in this example. The sequence of orders 1, 2, 3 is fixed in `visited_locations`. Orders 4 and 5 can be delivered in any sequence.
[API request (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/ee4315ef-ad6907c3-1e3caf-ae4a9b88) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/ee4315ef-ad6907c3-1e3caf-ae4a9b88) ⋅ [View on map](https://yandex.com/courier/mvrp-map#ee4315ef-ad6907c3-1e3caf-ae4a9b88)
**Example 2**
In `visited_locations`, it's specified that the route must start with order 2 at 10:00.
[API request (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/b72a3c31-d08ce81d-dd965f31-9b143db3) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/b72a3c31-d08ce81d-dd965f31-9b143db3) ⋅ [View on map](https://yandex.com/courier/mvrp-map#b72a3c31-d08ce81d-dd965f31-9b143db3)
**Example 3**
The order sequence 1, 2, 3 is set as in example 1. It's also specified that departure from order 1 must be at 08:20 and from order 3 at 11:00.
[API request (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/87d9729b-6d6d8d12-7e59415e-8eded514) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/87d9729b-6d6d8d12-7e59415e-8eded514) ⋅ [View on map](https://yandex.com/courier/mvrp-map#87d9729b-6d6d8d12-7e59415e-8eded514)
**Example 4**
There are 8 orders in this example. The specified sequence is orders 1, 2, 3, then the depot, then order 4. The courier may deliver the remaining orders in any sequence.
[API request (JSON)](https://courier.yandex.ru/vrs/api/v1/log/request/d50df3d9-3507050c-d748c21e-bcc23db3) ⋅ [API response](https://courier.yandex.ru/vrs/api/v1/result/d50df3d9-3507050c-d748c21e-bcc23db3) ⋅ [View on map](https://yandex.com/courier/mvrp-map#d50df3d9-3507050c-d748c21e-bcc23db3)
{% include [warehouse-feedback](_includes/feedback-81845556eeea.md) %}