Working with depots

When planning a route, you can use vehicle properties to specify different scenarios for the start and end of the route, work with multiple depots, add intermediate stops and intermediate loading, or require a return to a depot or another location at the end of the run.

Load handling time at depot

The loading or unloading time at a 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.

Example

Two 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 using the vehicle.depot_extra_service_duration_s parameter: 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 start the route immediately, 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 a parking spot). That's a usual task for sales representatives, service engineers, and other specialists who provide services rather than deliver goods.

You can set this requirement using the vehicle.start_atproperty. In this case, a courier or vehicle will start their route from the specified point with the garage type rather than from a 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 set it to true, the courier or vehicle should visit the depot before starting the delivery (this is default behavior). Otherwise, they can start delivering orders immediately. 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, set to 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 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 point 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:

1. 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.
2. 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.

To allow a courier to visit any of the depots specified during planning, use the vehicle.allow_all_depots parameter. For more information, see Working with all depots.

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 multiple depots

To allow a 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 depot_id and starting_depot_id fields aren't filled for the courier, they start from the first depot in the depots list.

If you use the delivery from one of several depots feature, 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 a courier to be able to visit additional depots for additional loading 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 these depots in the Depots that the courier can visit (vehicle.depot_id in the API) or Depots for additional loading (vehicle.middle_depot_id in the API) field. If there are orders in several depots, the algorithm will select the optimal depot for additional loading.

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.

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

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 one run each, starting at any depot and ending the route at any depot. Both couriers are allowed to visit different depots during one run, but they can't 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

Working with all depots

If you use many depots when planning and couriers can visit any of them, use the parameter vehicle.allow_all_depots = true.

In this case, you can add any depot to the courier's route without specifying it separately in the vehicle parameters.

Example 1

The courier needs to deliver four orders linked to different depots. The courier has the following parameters specified:

• Depot for visiting: vehicle.depot_id = 50.
• Depot to end the route at: vehicle.ending_depot_id = 10.
• Intermediate depot: vehicle.middle_depot_id = 20.
• Depot for additional loading: vehicle.starting_depot_id = 50.

The vehicle.allow_all_depots parameter isn't set and has the false value by default. As a result of planning, only depots 10, 20, and 50, as well as orders 3 and 4, are included in the route.

The rest of the orders linked to other depots haven't been included in the route because these depots aren't specified in the courier parameters and are considered unavailable to them.

API request (JSON) ⋅ API response ⋅ View on map

Example 2

The same as in example 1, but vehicle.allow_all_depots = true. As a result of planning, all the depots and orders have been included in the route.

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 (the locations.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_atproperty 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.

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 a courier starts or finishes it with the order that is the closest to a depot or the furthest from it. 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 it closer to the depot in the evening.

If you aren't 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 one 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

Contact support