Working with the depot
Load handling time at depot
The loading or unloading time at the depot may depend both on orders and vehicle properties (for example, dimensions or equipment).
To specify the amount of additional time required for loading at the depot, use the vehicle.depot_extra_service_duration_s
parameter. The time is set in seconds.
Note
The time assigned in the vehicle.depot_extra_service_duration_s
parameter is summed up with the depot handling time.
Example
2 vehicles with the same load capacity are delivering 13 large orders. The handling time at the depot depot.service_duration_s
is 5 minutes (300 seconds). Additional time is set for loading orders into a vehicle at the depot vehicle.depot_extra_service_duration_s
: 30 minutes (1800 seconds). As a result of planning, each vehicle will spend 35 minutes at the depot before starting their routes.
API request (JSON) ⋅ API response ⋅ View on map
Start of a loaded vehicle
If a vehicle is loaded in advance and there is no need to spend time loading it at the beginning of the shift, use the starts_loaded
= true
vehicle property. The handling time before the first run will then be ignored for this vehicle during route planning.
Example
Two vehicles deliver orders: the first one is loaded in advance, and the second one has to be loaded at the start of the shift. The handling time depot.service_duration_s
is 10 minutes (600 seconds).
As a result of planning, the first vehicle will immediately start the route, and the second vehicle will spend 10 minutes at the depot before departing.
API request (JSON) ⋅ API response ⋅ View on map
Vehicle started not from the depot
By default, vehicles and couriers start from the depot. However, sometimes they need to start the route from another point (for example, from their home or parking spot). That's a usual task in the case of sales representatives, service engineers, and other specialists who don't deliver goods, but provide services.
You can implement this requirement using the property vehicle.start_at
. In this case, the courier or vehicle will start their route from the specified point with the type garage
, rather than from the depot.
Visiting the depot before the start of the working day
At the beginning of the working day, couriers may need to visit the depot to get their orders there. Use the property vehicle.visit_depot_at_start
to enable this. If you specify true
, the courier or the vehicle must visit the depot before starting the delivery (this is default behavior). Otherwise, they can immediately start delivering orders. For more information, see Start or end of the route at an arbitrary point.
If couriers start from a garage
location, but they need to pick up some orders at the depot, enable the option Can visit the depot at the beginning of the route (can_visit_depot_at_start
in the API, false
by default). This option only works for couriers that have the parameter visit_depot_at_start
= false
. For orders that need to be picked up from a depot, specify one of the following parameters:
— depot_id
to link the order to a depot.
— depot_ready_time
, the time when the order is ready at the depot.
— depot_expiring_time
, the deadline for picking up the order from the depot.
You can also implicitly allow couriers to visit the depot at the beginning of the route with the can_visit_depot_at_start
option disabled by explicitly specifying the depot in planned_route
, fixed part of the route, or during additional planning.
Example 1
Three vehicles deliver orders: The first one starts the delivery from the depot. The second one starts and ends the route without visiting the depot. The starting point for the courier is order 6, which has the garage
type. The third one starts the route not from the depot, but from order 4 (the garage
type), but must visit the depot before starting the delivery.
API request (JSON) ⋅ API response ⋅ View on map
Example 2
Three vehicles deliver orders: The first one starts the delivery from the depot. The second and the third vehicles start and end the route without visiting the depot. Orders 1 and 7 have the pickup
type, and the algorithm selects them as the first route points.
Three separate routes are planned in the solution because of the orders priorities.
API request (JSON) ⋅ API response ⋅ View on map
Example 3
Two vehicles deliver orders (visit_depot_at_start
= false
and can_visit_depot_at_start
= true
). The first one starts from a garage
location and visits the depot to pick up order 1 at the beginning of the route. The second vehicle's route doesn't include a visit to the depot, it goes straight to the delivery.
API request (JSON) ⋅ API response ⋅ View on map
Making stops at multiple depots
Couriers can stop at multiple depots along their routes. This is helpful when items are stored in different depots or when the route needs to end at a specific depot.
Specify depots using one of these methods:
- On the Vehicles sheet in the Depots that the courier can visit field (
vehicle.depot_id
in the API), you can specify the depots that the courier is allowed to visit while following the route. They have a higher priority, so the algorithm can assign them as start, intermediate, or end depots. - In the fields:
- Depots to start from (
vehicle.starting_depot_id
in the API): The depots where the courier starts their route. - Depots for additional loading (
vehicle.middle_depot_id
in the API): The intermediate depots to pick up additional orders along the route. - Depots to end the route at (
vehicle.ending_depot_id
in the API): The depots where the courier completes the route.
Note
The depot_id
field has a higher priority than starting_depot_id
, middle_depot_id
, and ending_depot_id
. If a depot is specified in the depot_id
field, values in other depot fields are ignored.
Example 1
There are 9 orders in the planning task. Three depots are specified on the Vehicles sheet in the depot_id
field: Depot 1, Depot 2, and Depot 3. The courier is allowed to stop at multiple depots along the route.
As a result of planning, the courier:
- Starts the route from Depot 2, because it is located next to the first order location.
- Ends the route at Depot 3, because the last order location is next to it.
API request (JSON) ⋅ API response ⋅ View on map
Example 2
The courier must deliver 9 orders. Planning involves 2 depots:
- Depot 2: a start (
starting_depot_id
= 2) and end (ending_depot_id
= 2) depot. - Depot 1: an intermediate depot (
middle_depot_id
= 1).
As a result of planning, the courier starts the route at Depot 2 and delivers 4 orders. Then the courier stops at Depot 1 for reloading, delivers the remaining orders, and ends the route at Depot 2.
API request (JSON) ⋅ API response ⋅ View on map
Example 3
The courier must deliver 9 orders. Planning involves 3 depots:
- Depot 1: a start depot (
starting_depot_id
= 1). - Depot 2: an intermediate depot (
middle_depot_id
= 2). - Depot 3: an end depot (
ending_depot_id
= 3).
The courier is allowed to visit the intermediate depot for reloading at the beginning of the route only (vehicle.depots_only_at_run_beginning
= true
). As a result of planning, the courier starts from Depot 1, then stops at Depot 2 for reloading, and starts delivering orders. Ends the route at Depot 3.
API request (JSON) ⋅ API response ⋅ View on map
Start from one of several depots
To allow the courier to start from one of multiple depots, list them in the Depots that the courier can visit (vehicle.depot_id
in the API) or Depots to start from field (vehicle.starting_depot_id
in the API). If there are several depots, the algorithm will choose the optimal depot to start from. If the fields depot_id
and starting_depot_id
are not entered for a courier, they start from the first depot in the depots
list.
Alert
On the Vehicles sheet in the Depots that the courier can visit (depot_id
) and Depots for loading (starting_depot_id
) fields, you can't specify both regular and cross-docking depots at once. In a single route, a courier may only visit either regular depots or cross docks.
If you use the delivery from one of several depots functionality, a courier will be able to pick up orders from any depot they can visit.
For the courier, you can also set the parameters Allowed to visit multiple depots in one route (vehicle.allow_different_depots_in_route
in the API) and Maximum number of depots for additional loading in one route (vehicle.max_middle_depots
in the API). For more information, see Choosing the optimal depot to start from.
Additional loading at an intermediate depot
For the courier to be able to visit additional depots for reloading along the route, set the Allowed to visit multiple depots in one route (vehicle.allow_different_depots_in_route
in the API) parameter to true
. Specify depots for reloading in the field Depots that the courier can visit (vehicle.depot_id
in the API) or Intermediate depots (vehicle.middle_depot_id
in the API). If there are orders in several depots, the algorithm will select the optimal depot for reloading.
Alert
On the Vehicles sheet in the Depots that the courier can visit (depot_id
) and Intermediate depots (middle_depot_id
) fields, you can't specify both regular and cross-docking depots at once. On a single route, a courier may only visit either regular depots or cross docks.
If the courier can stop at intermediate depots for additional loading at the beginning of the route only (before completing the first order), set the vehicle.depots_only_at_run_beginning
parameter to true
(by default, it's set to false
).
For the courier, you can also set the Maximum number of depots for additional loading in one route parameter (vehicle.max_middle_depots
in the API). For more information, see Visiting an additional depot.
Returning to a depot at the end of the route or run
By default, the courier completes the route at the depot where they started. To allow the courier to stop at multiple depots along the route, set the Allowed to visit multiple depots in one route parameter (vehicle.allow_different_depots_in_route
in the API) to true
. In this case, the courier can end the route at a depot other than the first one.
Specify the depots where the courier can complete the route in the Depots that the courier can visit (vehicle.depot_id
in the API) or Depots to end the route at field (vehicle.ending_depot_id
in the API). If there are several depots, the algorithm will choose the optimal depot to complete the route at.
Alert
On the Vehicles sheet in the Depots that the courier can visit (depot_id
) and Depots to end the route at (ending_depot_id
) fields, you can't specify both regular and cross-docking depots at once. On a single route, a courier may only visit either regular depots or cross docks.
If you want the courier to end the route at the same depot where they started it, set the vehicle.finish_route_in_starting_depot
parameter to true
(by default, it's set to false
). In this case, if the courier's starting location is not a depot (vehicle.visit_depot_at_start
= false
), they will need to return to the depot where they started the second run of the route.
If you want the courier to end each run at the same depot where it was started, set the vehicle.finish_run_in_starting_depot
parameter to true
(by default, it's set to false
). To allow the courier to change depots between runs, set the vehicle.can_change_depot_between_runs
parameter to true
. For more information, see Start of a new run from a different depot.
Note
It only makes sense to set vehicle.finish_route_in_starting_depot
to true
and vehicle.finish_run_in_starting_depot
to true
if vehicle.allow_different_depots_in_route
is also true
.
If the courier doesn't have to return to the depot after completing all orders, set Return to depot at the end of the shift (vehicle.return_to_depot
in the API) to false
.
Example 1.1
Two couriers are to deliver two orders: one is a delivery
order that needs to be picked up from Depot 1, and the other one is a pickup
order to be delivered to Depot 2. The couriers can only make 1 run each, starting at any depot and ending the route at any depot. Both couriers are allowed to stop at different depots during one run, but they cannot stop at intermediate depots.
The solution uses only one courier: they leave Depot 1 after picking up the delivery
order, deliver it, pick up the pickup
order, and deliver it to Depot 2, where they end the route.
API request (JSON) ⋅ API response ⋅ View on map
Example 1.2
The same as in example 1.1, but the couriers need to end routes at the same depot where they started them (vehicle.finish_route_in_starting_depot
= true
).
The solution uses both couriers. Courier 1 leaves Depot 1 after picking up the delivery
order, delivers it, and returns to Depot 1. The second courier leaves Depot 2, picks up the pickup
order, and returns with it to Depot 2.
API request (JSON) ⋅ API response ⋅ View on map
Return to any location at the end of the route
If your work scenario needs to take into account the distance of the last order from the courier's parking spot (or home address, for example), you can implement it as follows:
-
Create a point with the
garage
type (thelocations.type
field). This point will only be used to end the routes. -
For a courier who needs to return home or to the parking spot at the end of their working day, enter the ID of this point in the
vehicle.finish_at
field.
In the solution, all vehicles or couriers that have the finish_at
property specified return to the specified point. If the option to return to the depot is enabled (vehicle.return_to_depot
= true
), the route will first go the depot and then to the parking spot.
Example
The example below uses two vehicles with different load capacities and four orders with different weights. Two vehicles are used for delivery because of the weight restrictions. Vehicle 2 doesn't have to return to the depot after it delivers the last order.
Note
Note that in the RouteQ response, vehicle 2 completes the route at the last order location.
API request (JSON) ⋅ API response ⋅ View on map
Start or end of the route as close to the depot as possible
You can plan a route so that the courier starts or finishes on the order that is closest to or furthest from the depot. For example, if you expect to get new orders in the morning, then it would be better to start the route with the orders closest to the depot. That way, it will be easier for the courier to return to the depot to pick them up. On the other hand, by starting the route with the farthest order, the courier would finish closer to the depot in the evening.
If you are not using advanced cost settings, set the following parameters:
-
first_edges_penalty_factor
: A penalty for the distance from the depot to the first order, the default is 0. If the value is greater than 0, the algorithm minimizes this distance, and if the value is less than 0, it maximizes the distance. -
last_edges_penalty_factor
: A penalty for the distance from the depot to the last order, the default is 0. If the value is greater than 0, the algorithm minimizes this distance, and if the value is less than 0, it maximizes the distance.
Penalties are calculated similarly to the duration and length of route segments (see the Travel between route points group under Advanced cost settings).
If penalty values are high, routes may be suboptimal in terms of mileage. If penalty values are low, then the first or last order of a route may be selected in violation of any requirements provided it saves on mileage.
If you use advanced cost settings, use the keywords from the Travel from or to the depot group.
Example
In the example below, there is 1 courier and 10 orders. Two penalties are set: first_edges_penalty_factor
= 2 and last_edges_penalty_factor
= -2. Planning produces a route that begins with the order closest to the depot and ends with the furthest order.
API request (JSON) ⋅ API response ⋅ View on map