Depot properties
A depot is a location where all routes can start and end. If you have couriers that do not start from the depot, read the instructions Vehicle started not from the depot.
To define the depots, use the depot
/depots
field in the request.
Depot ID
Each depot must have a unique numeric or string ID set in the id
field. The ID must be unique within a single request.
Alert
The depot ID must not be the same as any order IDs.
You can also specify the depot's numeric or string ID from your tracking system in the ref
field: this ID will be displayed in the Planning section of the resulting solution. You can specify the depot's name in the title
field and describe the depot in the description
field: these fields won't be displayed in the interface but will be passed to the solution.
Depot coordinates
RouteQ supports WGS84 coordinates for defining the depot location (address). Coordinates are specified in the point
field as two values: point.lat
(latitude) and point.lon
(longitude).
Alert
The coordinates 0,0
will not be processed correctly and will result in an error when you send a request to RouteQ.
When planning via Excel, you can only specify the depot address in the address
field. In this case, geocoding will be performed: the coordinates of the specified address will be determined. For more information, see the Map section.
Depot type
By default, all depots have a depot
type. Intermediate platforms can be used for the transshipment, reconsolidation, or reloading of goods. The type
field for these depots is crossdock
. To learn more about working with such depots, see our cross-docking scenarios.
Depot time window
The depot in the request must have a time window with the depot's working hours.
To define the depot's working hours, use the time_window
field.
The time window can be defined inone of the following formats:
-
07:00:00–23:00:00
: The time window starts at 7:00 and ends at 23:00 on the current day. -
2019-10-10T07:00:00+03:00/2019-10-10T23:00:00+03:00
: The time window for a specific date and time zone (read as YYYY-MM-DDThh:mm:ss±hh:mm).
Depending on the type of time window, vehicles that need to end their route at the depot can only return before the end of the depot's working hours (a hard time window) or violate this restriction (a soft time window). For more information, see Hard and soft time windows.
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.
With a soft time window, additional penalties can be set for its violation. This functionality is described in more detail in Penalties for the depot's time window violation.
To limit permissible violations of the main window, you can set a hard time window around a soft one.
Note
The hard_time_window
and hard_window
fields are mutually exclusive.
Departing from the depot is also possible before the time window starts. This case is discussed in detail in Flexible start time.
Note
When you specify a depot's time window, keep in mind cases when the vehicle needs to return to the depot. If the vehicle can't return to the depot on time and the depot's window is hard, some orders may not get delivered. When in doubt, set the depot's working hours for the whole planning period and make the working hours flexible.
Multiple time windows of the depot
If necessary, you can enter multiple time windows for a depot. This is useful in the following situations:
-
The depot has a break. A common example is a lunch break.
-
The courier is on a multi-day route. For example, orders must be delivered at a specific time, but on any one of the appointed delivery days, and there is a break at the depot that may affect loading orders.
-
If orders are planned for multiple days for a courier and some of the orders can be picked up or delivered only on certain days.
In the time_windows
field, an array of elements is specified. Each element of this array contains the required time_window
field. Orders are loaded at the depot during one of the available windows. The information about which time window has been used is contained in the used_time_window
field of the API response.
Alert
Windows set in time_window
must not overlap. For example, you can't specify windows between 9:00–12:00 and 11:00–14:00 at the same time.
You can set an additional hard window for every depot time window. It's used to limit the allowed time of a main window violation and is defined with the hard_time_window
parameter.
Example
A courier delivers 10 orders: some have to be delivered before noon, others in the afternoon. The depot has a lunch break from 13:00 to 14:00. The courier delivers part of the orders and returns to the depot for reloading during the depot's break. When the break ends, they load and deliver the remaining orders.
API request (JSON) ⋅ API response ⋅ View on map
Time windows for loading, unloading, and reloading
In addition to the time windows that set working hours, additional windows can be set for the depot to limit certain operations:
time_windows_loading
: Loading windows. These define the time when a courier visits the depot for the first time per shift.time_windows_unloading
: Unloading windows. These define the time when the courier visits the depot for the last time per shift.time_windows_refilling
: Reloading windows. These define the time when the courier comes to the depot for reloading. This can be the main depot or an intermediate depot.
Note
If an additional window is not set, the general depot time window is used for the corresponding operation.
You can set multiple additional windows of each type for a depot. In this case, the time_windows
array should be used for setting these windows.
For an additional window, one of the following parameters can be specified:
-
hard_window
: Defines if the additional window is hard or soft (this parameter is set for the entire array of additional windows of each type).- If there is a hard additional window, waiting times may be added to the route. If requirements can't be met, some orders may be added to the list of unassigned orders.
- If there is an additional soft window, at least one penalty must be set in case of violations.
-
hard_time_window
: Sets a hard time window around a soft time window (this is set separately for eachtime_window
parameter).
Example
A depot has the following general time window: 7:00–21:00
. The following windows are also set:
- A hard time window for loading:
7:00–9:00
. - Soft time windows for reloading:
11:00–12:00
and14:00–15:00
. - A hard time window from
17:00–20:00
for unloading around a soft time window from18:00–19:00
.
A vehicle has a weight limit of 200 kg. Since all orders are heavier than 100 kg, the courier returns to the depot for reloading after every order.
Under these conditions, the optimal route is built as follows:
- When visiting the depot for the first time per shift, the courier loads order 1 and fits into the loading time window. After the order is delivered, the courier returns to the depot right in time for the start of the first reloading time window.
- During the second run, the courier picks up order 2 from the depot and delivers it, then returns to the depot again and waits 44 minutes for the second loading time window to start.
- During the third run, the courier picks up order 3 from the depot, delivers it, and then picks up order 4.
- At the end of the shift, the courier returns to the depot to unload order 4. They are 33 minutes late for the soft unloading time window, but on time for the hard time window.
API request (JSON) ⋅ API response ⋅ View on map
Enable or disable grouping options
The depot.use_in_proximity
option selectively disables options.proximity_factor and options.global_proximity_factor that are responsible for grouping routes.
By default, depot.use_in_proximity
= true
, meaning the grouping options apply to all depots. For more information, see Grouped routes.
Handling time at depot
RouteQ lets you set the total handling time that any vehicle or courier should spend at the depot. The total handling time at the depot can be used to account for the courier's paperwork or average vehicle loading time:
-
depot.preliminary_service_duration_s
: Time before the start of each run until the order is ready at the depot. -
depot.service_duration_s
: Time before the start of each run after the order is ready at the depot. -
depot.load_service_duration_s
: Time to loaddelivery
orders into the vehicle. It is added to the depot handling time if at least onedelivery
order is loaded there. -
depot.unload_service_duration_s
: Time to unloadpickup
orders from the vehicle. It is added to the depot handling time if at least onepickup
order is unloaded there. -
depot.finish_service_duration_s
: Time before the end of each run.
If order ready time isn't used, you don't need to specify preliminary_service_duration_s
. Instead, service_duration_s
can be set as the total time.
Note
You can set the order-specific loading time at the depot. For more information, see Load handling time.
Example 1
Let's set a handling time of 10 minutes at the start and end of any route for a depot that opens at 07:00.
In the resulting route, the arrival time at the first order is 07:28, and the trip to the first order takes 18 minutes. The vehicle spent 10 minutes at the depot before starting the trip.
At the end of the route, the arrival time at the depot is 07:53. 10 minutes of handling time are added to this, which affects metrics for the total route duration.
API request (JSON) ⋅ API response ⋅ View on map
Example 2
In this example, there are 3 orders. Each order takes up 100% of the vehicle's carrying capacity, so 3 separate runs are planned. You can see that depot.service_duration_s
and depot.finish_service_duration_s
are added at the beginning and end of each run, respectively.
API request (JSON) ⋅ API response ⋅ View on map
Example 3
An order will be ready for delivery from a depot at 08:00:00 (location.depot_ready_time
). Before the order is ready, you have 30 minutes to perform any preliminary operations at the depot (depot.preliminary_service_duration_s
). As soon as the order is ready, 10 minutes will be spent on handling (depot.service_duration_s
). The total handling time is from 07:30:00 to 08:10:00.
API request (JSON) ⋅ API response ⋅ View on map
Flexible start time
By default, couriers start departing from the depot as soon as the depot is open (or the courier's shift starts) and orders are loaded. In this case, the value of the parameter depot.flexible_start_time
is false
.
If you set the value to true
, departure from the depot will be planned sometime after the start of the depot's time window or the courier's shift.
Example 1
A courier's shift starts at 09:00, and the depot opens at 08:30. The depot.flexible_start_time
parameter is set to false
. Planning takes into account that any route assigned to this courier must start at 09:00, even if the first order's window is from 13:00 to 14:00, and it takes 15 minutes for the courier to get from the depot to the order location.
API request (JSON) ⋅ API response ⋅ View on map
Example 2
A courier's shift starts at 09:00, and the depot opens at 08:30. The depot.flexible_start_time
parameter is set to true
. If the first order's window is from 13:00 to 14:00, and it takes 15 minutes for the courier to get from the depot to the order location, the planner may plan the courier's departure later than 09:00 (for example, at 12:30), unless other restrictions are violated.
API request (JSON) ⋅ API response ⋅ View on map
Delivery from one of several depots
Sometimes the product is available in several depots, and during planning you need to select the depot to deliver from. If you know which depots a particular order should be shipped from, use the location.depot_id parameter. In the parameter value, specify the array of id
of these depots.
For vehicles, you can specify which depots to start from. This will assign the order to the depots.
Example 1
You are given two cars, two depots, and three orders.
Vehicles start from certain depots:
-
The first vehicle from depot 1.
-
The second vehicle from depot 2.
As a result of planning:
- The first vehicle delivers order 3 from depot 1.
- The second vehicle delivers orders 1 and 2 from depot 2.
API request (JSON) ⋅ API response ⋅ View on map
Example 2
The same as in example 1, but orders are assigned to depots:
- Order 1 is assigned to depots 1 and 2.
- Order 2 is assigned to depot 1.
- Order 3 is assigned to depot 2.
As a result of planning:
- The first vehicle delivers orders 1 and 2 from depot 1.
- The second vehicle delivers order 3 from depot 2.
API request (JSON) ⋅ API response ⋅ View on map
Depot throughput capacity
The depot throughput capacity depends on both the speed of loading orders into vehicles and the speed of preparing orders for loading (for example, packaging). The processes of preparing and loading orders are often parallel: while previously prepared orders are loaded into vehicles, the next batch of orders is being prepared for loading. However, the speed of preparing and the speed of loading orders may not be the same (for example, order preparation takes an average of 5 minutes while loading takes 1.5 minutes). The time windows of the order preparation and loading processes may also not be equal (for example, order preparation starts in advance).
You can set the depot throughput separately for each process.
With throughput specified correctly, you can plan a realistic depot departure time.
Vehicle loading speed at the depot
To limit the loading speed, use the depot.throughput
request field. You can set one of the restrictions:
-
throughput.kg_per_hour
: Throughput loading capacity in kg/hour. -
throughput.units_per_hour
: Throughput loading capacity in units/hour (pallets, boxes, kegs). -
throughput.vehicle_count
: Throughput loading capacity in vehicles. This parameter lets you take into account loading dock availability at the depot. Only one vehicle can park at each dock at a time.
The depot throughput capacity may vary depending on the time of day (for example, if more loaders work during peak hours). For each time interval N
, you need to set two fields that determine:
- Time window:
throughput.kg_per_hour.N.time_window
,throughput.units_per_hour.N.time_window
, orthroughput.vehicle_count.N.time_window
. - Throughput during this time window:
throughput.kg_per_hour.N.value
,throughput.units_per_hour.N.value
, orthroughput.vehicle_count.N.value
.
When you set the parameter values, note the following restrictions:
- Throughput windows should not overlap.
- If all throughput windows don't cover the working time of a depot, throughput between time windows is considered 0.
- Throughout windows can cover the time outside a depot's working hours to account for vehicles that can arrive before the start or after the end of a depot's working hours.
If the loading handling time is specified for the order, it's included in the throughput capacity limit check along with the order weight or number of units.
If the load handling time doesn't depend on order characteristics, but is based entirely on the depot and the vehicle, use the vehicle.depot_extra_service_duration_s
field. In the field, specify how much more load handling time in seconds is required in addition to the depot's general handling time. For more information about this parameter, see Load handling time at depot.
Alert
To take the depot throughput capacity into account during planning:
-
Enable flexible start time.
-
Set the handling time and/or the load handling time.
The recommended load handling time (
service_duration_s
) value is at least 10 minutes (600 seconds).
If the depot throughput capacity is violated, the following penalties apply:
-
depot.penalty.throughput.fixed
: For each violation. -
depot.penalty.throughput.kg
: For each kg over thethroughput.kg_per_hour
limit. -
depot.penalty.throughput.unit
: For each cargo unit over thethroughput.units_per_hour
limit. -
depot.penalty.throughput.vehicle
: For violations of the number of vehicles during loading or unloading.
If a vehicle arrives too early or too late to a depot, penalties are applied both for the violation of a depot's time window and for exceeding the number of vehicles when loading or unloading depot.penalty.throughput.vehicle
. To avoid double penalties, set throughput windows so that they go beyond a depot's working hours and account for possible early and late arrivals of vehicles.
Example 1
In the example there are 20 orders. The total number of cargo units is 1170. The handling time is 1 hour. The throughput capacity isn't set, so all couriers start at approximately the same time believing that all orders can be loaded simultaneously.
API request (JSON) ⋅ API response ⋅ View on map
Example 2
The same as example 1, but a limit was set on the number of vehicles that could be loaded simultaneously at the depot using the parameter throughput.vehicle_count
= 3. This way, no more than 3 vehicles are loaded at the depot at the same time: first, vehicles 2, 3, and 4, and then vehicle 1.
API request (JSON) ⋅ API response ⋅ View on map
Example 3
The same as example 1, but a limit was set on the number of vehicles that could be loaded simultaneously at the depot using the parameter throughput.vehicle_count
. Also, the depot throughput capacity is different at different times:
-
06:00 — 07:30
: 2 vehicles. -
07:30 — 22:00
: 1 vehicle.
API request (JSON) ⋅ API response ⋅ View on map
Example 4
The same as example 1, but with a depot throughput capacity limit throughput.units_per_hour
= 300: only 300 units can be loaded per hour. This way, order loading is distributed realistically. Now couriers arrive only after the previous courier finishes loading.
API request (JSON) ⋅ API response ⋅ View on map
Staging speed
To limit the staging speed, the depot.package_throughput
field is used. You can set one of the following limits:
-
package_throughput.kg_per_hour
: Staging throughput capacity in kg/hour. -
package_throughput.units_per_hour
: The maximum number of cargo units for staging at the depot in one hour.
Staging throughput capacity may vary depending on the time of the day (for example, if more depot employees handle packaging during peak hours). For each time interval N
, you need to set two fields that determine:
- The time window:
package_throughput.kg_per_hour.N.time_window
orpackage_throughput.units_per_hour.N.time_window
. - Throughput during this time window:
package_throughput.kg_per_hour.N.value
orpackage_throughput.units_per_hour.N.value
.
When you set the parameter values, note the following restrictions:
- Throughput windows should not overlap.
- If all throughput windows don't cover the working time of a depot, throughput between time windows is considered 0.
- Throughout windows can cover the time outside a depot's working hours to account for vehicles that can arrive before the start or after the end of a depot's working hours.
If during planning, the depot throughput capacity to prepare for loading is violated, the following penalties apply:
-
depot.penalty.throughput.fixed
: For each violation. -
depot.penalty.package_throughput.kg
: For each kg overpackage_throughput.kg_per_hour
. -
depot.penalty.package_throughput.unit
: For each cargo unit overpackage_throughput.unit_per_hour
.
Example 5
The same as in Example 1, but with a throughput capacity limit for order staging: 180 units can be packaged from 06:00 to 10:00 at the depot in an hour while 120 units can be packaged from 10:00 to 22:00. A penalty is imposed if the staging throughput capacity is violated: penalty.package_throughput.unit
= 100.
To send vehicles on runs on time, the depot staging throughput capacity limit was violated, so a penalty was imposed: total_depot_penalty
= 9500.
API request (JSON) ⋅ API response ⋅ View on map
Penalties for the depot's time window violation
This penalty is added to the total cost of the route, if the vehicle departs from the depot before the depot's time window or returns to the depot later than the depot's time window.
Note
This is only possible if you set a soft time window. If a hard time window is violated, the order is automatically marked as undelivered and excluded from all routes.
A penalty for late arrival at the depot lets you violate the depot's time window if orders can't be loaded into a vehicle within the specified time window.
To make sure vehicles and couriers arrive at the depot on time, you can use the following objects in RouteQ:
-
depot.penalty.early
: Sets a penalty for arrival at the depot before the time window starts. -
depot.penalty.late
: Sets a penalty for return to the depot after the time window ends. -
depot.penalty.out_of_time
: Sets the same penalties for both early arrival and late return to the depot.
If depot.penalty.early
and depot.penalty.late
are not set, the values of depot.penalty.out_of_time
are used (early
and late
override the out_of_time
parameter).
Each object consists of two fields:
-
fixed
: A fixed penalty for each single untimely arrival at the depot. -
minute
: A penalty for each minute that arrival at the depot is early or late.
If only one value (fixed
or minute
) is set for depot.penalty.early
or depot.penalty.late
, then the second is taken from depot.penalty.out_of_time
. For example, only depot.penalty.late.fixed
can be set. In this case, depot.penalty.out_of_time.minute
will be used as a per-minute penalty for late arrival at the depot.
Note
The above fields have default values. We recommend using them as the starting values for defining custom priorities for arriving at the depot.
When in doubt, contact RouteQ analysts to determine the correct coefficients.