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.

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 also 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).

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 in one 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.

Departing from the depot is also possible before the time window starts. This case is discussed in detail in Flexible start time.

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.

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.

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 each time_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 and 14:00–15:00.
• A hard time window from 17:00–20:00 for unloading around a soft time window from 18: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 load delivery orders into the vehicle. It is added to the depot handling time if at least one delivery order is loaded there.

• depot.unload_service_duration_s: Time to unload pickup orders from the vehicle. It is added to the depot handling time if at least one pickup 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.

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:

1. The first vehicle delivers order 3 from depot 1.
2. 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:

1. The first vehicle delivers orders 1 and 2 from depot 1.
2. 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, or throughput.vehicle_count.N.time_window.
• Throughput during this time window: throughput.kg_per_hour.N.value, throughput.units_per_hour.N.value, or throughput.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.

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 the throughput.kg_per_hour limit.

• depot.penalty.throughput.unit: For each cargo unit over the throughput.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 or package_throughput.units_per_hour.N.time_window.
• Throughput during this time window: package_throughput.kg_per_hour.N.value or package_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 over package_throughput.kg_per_hour.

• depot.penalty.package_throughput.unit: For each cargo unit over package_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.

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.

Contact support