Possible logistic scenarios

  1. Delivery from a single depot
  2. Cargo collection to the depot
  3. Start or end of the route at an arbitrary point
  4. Pickup & delivery: collecting and delivering cargo at arbitrary points
  5. Delivery from one of several depots
  6. Delivery from several depots
    1. Visiting an additional depot
    2. Choosing the optimal depot to start from
  7. Delivery to one out of multiple points
  8. Receiving cargo at one of the possible points
  9. Planning multiple runs from the depot for one courier
  10. Additional planning of the route
  11. Cross-docking
    1. Planning without considering the delivery distance to the cross-dock
    2. Pickup & delivery via a cross-dock
  12. Delivery with vehicle parking before the walking part of the route

For all logistic scenarios, be sure to specify depots, orders, and couriers. The data set is dependent regarding the couriers and orders in it. If they can be divided into independent parts (so that a group of orders is only carried out by certain vehicles and there's no mixing), we recommend making multiple separate planning runs, each with its own set of orders and couriers. For example, do this if:

  • There are several depots, each depot ships its own set of orders, and each depot has its own set of vehicles.

  • Cargo is delivered from the depot and taken to the depot by different vehicles (and these are different independent orders).

  • A depot has several geographical zones, each of which is served by its own set of vehicles.

The logistic scenarios described below can be combined. If the above examples don't describe your business task, contact your RouteQ manager or support at routing-support@yandex-team.ru.

Delivery from a single depot

This is the default scenario when you need to plan the delivery of goods to your clients or build a route that visits a specified set of points. It's used if there's only one depot in the request, and orders have the delivery type specified in the location field, or this field isn't set (see Order type). The algorithm will build a route for delivery of all orders from the specified depot.

Diagram

Example

There are 30 orders in this solution. All of them are delivered from a single depot. The order type isn't explicitly specified, so its default value is delivery .

API request (JSON) API response View on map

Cargo collection to the depot

This is the default scenario when cargo is collected from your clients to be delivered to the depot. For examples, such cargo may include:

  • Medical tests that are taken at home.

  • Clothes for dry cleaning.

  • Goods that your clients return to the depot.

In the last case, this scenario is often combined with delivery from a single depot.

To specify pickup points, specify the order type = pickup (see Order type). After that, different options are possible:

  1. All vehicles must return to the depot at the end of the day (see Return to the depot at the end of the working day), meaning return_to_depot = true. In this case, you don't need to configure anything else, and the vehicle completes the route at the depot by default.
  2. The cargo must stay in the courier's vehicle and be returned to the depot the next morning when the courier arrives for their next shift. To do this, set return_to_depot = false. The route will end at the last pickup point. You don't need to configure anything else in this case, either.
  3. Not all vehicles return to the depot at the end of the day. The algorithm chooses which ones must return. The return_to_depot = false option is used, and delivery_deadline needs to be set (time of order delivery to the depot). The delivery_deadline option must be specified for all pick-up points. It's enough to specify a time that's definitely outside the time limits of the routes. This option is usually used for a mixed scheme, when part of the cargo is delivered from the depot and part of the cargo must be returned to the depot.

Diagram

Example 1

Cargo is picked up and taken to the depot. All vehicles must return to the depot at the end of the day (return_to_depot = true ). There are 30 orders, 1 depot, and 5 cargo pickup points.

API request (JSON) API response View on map

Example 2

The source data is the same as in the previous example. One of the vehicles has return_to_depot = false specified. This means that the cargo will remain in the courier's vehicle and return to the depot the next morning.

API request (JSON) API response View on map

Example 3

In the example, there are 30 orders, 1 depot, and 5 cargo pickup points (different pickup points are selected). For all vehicles, return_to_depot = false , and delivery_deadline is specified for the pickup points. At the end of the day, only the vehicle that has all the pickup orders will return to the depot.

API request (JSON) API response View on map

Start or end of the route at an arbitrary point

Situations to use this in

By default, the courier route starts and ends at the depot. However, in some cases, you may need to plan a route from the vehicle's parking spot or from the courier's home. Or the other way around: you may need to complete the route closer to these points.

How to implement this scenario

Start points are defined using the start_at and visit_depot_at_start parameters. End points are defined using the finish_at and return_to_depot parameters.

Tip.

Not all combinations of these parameters in the solution use a depot (for example, if all couriers start from home and immediately go to order locations), but it is still required in the data scheme. In this case, you can specify the coordinates of the office or city center as a depot.

The parameters of the start and end points are independent of each other, so you can configure any combination here:

  • Set start and end points separately for each courier.

  • Specify the same point for multiple couriers.

  • Specify the same start and end points.

The garage order type is used to specify the start or end point. If vehicle.visit_depot_at_start = false, and vehicle.start_at isn't specified, the algorithm assumes that the courier can start the route from the first order without visiting the depot.

Restriction.

A combination of parameters where start_at isn't defined and visit_depot_at_start = false is applicable if the route has pickup or pickup & delivery orders. Orders delivered from the depot aren't planned first and appear in the route only after the courier visits the depot.

Schemes for start points

  • Starting a route from the order point without going to the depot (start_at isn't defined, visit_depot_at_start = false). The algorithm chooses the start point of the order for the courier.

  • Starting a route from the depot (start_at isn't defined, visit_depot_at_start = true ). The algorithm's default behavior.

  • Starting a route from a specific point without going to the depot (start_at is defined, visit_depot_at_start = false). Start points may differ for different couriers.

  • Starting a route from a specific point with a visit to the depot (start_at is defined, visit_depot_at_start = true). Start points may differ for different couriers.

Schemes for end points

  • Ending a route at the last point without returning to the depot (finish_at isn't defined, return_to_depot = false ).

  • Returning to the depot at the end of the route (finish_at isn't defined, return_to_depot = true ).

  • Ending a route at a specific point without returning to the depot (finish_at is defined, return_to_depot = false). End points may differ for different couriers.

  • Ending the route at a specific point with a visit to the depot before the end point (finish_at is defined, return_to_depot = true). End points may differ for different couriers.

Pickup & delivery: collecting and delivering cargo at arbitrary points

Situations to use this in

This scenario is used for planning door-to-door cargo delivery without involving intermediate depots or reloading points. For example:

  • Goods must be picked up from the supplier's depot and taken to the client (multiple pickup scenarios are supported for when you need to collect the goods from different suppliers at several depots and deliver them to the same client).

  • Goods are returned (you need to pick them up from the client and take them to the depot for returns, not to the main depot).

You can also use this scenario in cases where there are simple dependencies between points. For example, before you get to the client, you need to pick up tools, documents, or keys.

You can use this scenario together with the scenarios for collecting cargo at the depot and delivery from a single point.

How to implement this scenario

A distinctive feature of using the pickup & delivery scenario is that there's a pair of linked points, one of which must always be visited before the other: first pickup, then delivery. The points are linked using the delivery_to field: you fill it in for the pickup point, specifying the ID of the associated delivery .

In a multiple pickup scenario for several different pickup points, you can specify the same value in the delivery_to field. A group of multiple pickup orders and one delivery order will always be assigned to a single courier.

If there's one pickup point from which you need to deliver to multiple delivery points, specify different pickup & delivery pairs (the pickup orders will have the same coordinates, but they must have different IDs). Such pickup & delivery pairs can be assigned to different couriers (despite the fact that they have the same pickup point). For mandatory planning for one courier, we recommend using grouping locations.

Attention.

You don't have to specify the weight, volume, and number of places for delivery points, but they must be specified for the associated pickup order.

If you specify the volume and weight characteristics for a delivery point, they must be the same for the associated pickup order. That is, in case of more than one pickup, it's enough to specify the weight, volume, and number of places only for the pickup orders.

To control the sequence when carrying out pickup & delivery pairs, we recommend using location.in_lifo_order (for more information, see Order of reception and delivery).

Schemes

  • pickup & delivery.

  • Multiple pickup for one delivery point.

Example 1

We plan 12 different points. Half the points are pickup , and the other half are delivery . In total, we get 6 “door-to-door” deliveries.

API request (JSON) API response View on map

Example 2

We set 8 different addresses for pickup points and specify the same values for them in the delivery_to field. As a result, we get a plan in which a courier must pick up orders from different places and bring them all to one place.

API request (JSON) API response View on map

Example 3

Delivery is planned from 1 address to 6 different addresses. We set the pickup type for 16 points with the same address and the delivery type for the other 16 points.

API request (JSON) API response View on map

Delivery from one of several depots

Situations to use this in

This scenario is used when multiple depots have a ufficient quantity of the same goods, and you need to choose which depot to deliver them from when planning.

How to implement this scenario

Attention.

When using this scenario, list all couriers that start from each depot.

When planning, specify multiple depots and which depot each courier is assigned to (learn more in Delivery from one of several depots and Start from one of several depots).

For this scenario, you can also use the function for starting at an arbitrary point without visiting the depot (learn more in Start or end of the route at an arbitrary point when start_at is defined and visit_depot_at_start = false). If you specify the depot as the starting point where shipping must begin for each courier, the planning result will be the same as when planning from several depots.

Tip.

If you know which depot a particular order should be shipped from, use the location.depot_id parameter. Specify the depot id or an array of depot id in the parameter value.

This scenario can be implemented without the service functions, that is, if you create rigid links between an order and a depot. There are several ways to do this:

  • Nearest depot

    Calculate the distance between the coordinates of the order address and all depots (use the Distance matrix service for making the calculation). The nearest depot is selected for the order.

  • Delivery zone

    Each depot has a pre-defined delivery zone (drawn using Yandex Map Constructor). Each order is pre-checked to see which depot's delivery zone it falls into. Each depot is planned separately and independently following the Delivery from a single depot scenario.

Diagram

Example 1

In this example, the depot_id parameter is used to specify which depot each courier is linked to. This way, couriers deliver orders from their depots only.

API request (JSON) API response View on map

Example 2

In this example, couriers don't start their route from the depot. They start from one of two garage points. The start point of the route is defined using start_at.

API request (JSON) API response View on map

Example 3

Three depots, three orders, and three vehicles are given. Each vehicle starts from its own depot. Orders are assigned to depots using location.depot_id:

  • Order 1 is not assigned to a depot. It can be delivered from any depot.

  • Order 2 is assigned to depots 1 and 2. This order can be delivered from one of the two specified depots.

  • Order 3 is assigned to depot 3. It is located in a specific depot.

As a result, the algorithm calculated two routes:

  1. One courier serves orders 1 and 2 from depot 2.
  2. Another courier serves order 3 from depot 3.

API request (JSON) API response View on map

Delivery from several depots

Visiting an additional depot

Situations to use this in

A frequent scenario when planning is visiting an additional depot to pick up more orders:

  1. Couriers start from the main depot 1.

  2. Part of the couriers immediately go to deliver orders.

  3. Some couriers visit depot 2 to pick up more orders, because some clients' orders are stored there.

  4. The couriers who went to depot 2 can deliver some orders on their way to depot 2.

Important differences between this scenario and Choosing the optimal depot to start from:

  • This scenario has a main depot that's set in the depot object. Couriers start from there (depot_id).

  • Orders from the additional depot are set using pickup & delivery. The coordinates of pickup points are the same, and they must be created separately for each delivery order from the additional depot. If there are multiple additional depots, they're set by the corresponding pickup & delivery pair.

Tip.

If you have multiple depots, and couriers can go from each of them to the others, but the depots are independent by the set of couriers (each depot has its own set of vehicles that perform most deliveries), we recommend planning for each depot separately.

How to implement this scenario

Let's say there are 2 deliveries:

  1. From the main depot 1 to points 1 and 2.

  2. From an additional depot to points 1 and 2.

Enter information about all these deliveries in the following way:

  • Depot 1 → point 1 = delivery to point 1.

  • Depot 1 → point 2 = delivery to point 2.

  • Depot 2 → point 1 = pickup from Depot 2 + linked delivery to point 1.

  • Depot 2 → point 2 = pickup from Depot 2 + linked delivery to point 2.

Attention.

Enter each delivery for the weight and volume to be picked up from the corresponding depot.

Overall, you need to pass 6 points in the locations object despite the fact that there are 2 orders, each with a visit to an additional depot. This scenario is a combination of Delivery from a single depot and Pickup & delivery (collecting and delivering cargo at arbitrary points).

Diagram

Example

In this example, an additional depot is specified using pickup & delivery . The courier starts from the main depot, delivers an order, and visits an additional depot to collect more orders.

API request (JSON) API response View on map

Choosing the optimal depot to start from

Situations to use this in

In this scenario, you need to decide how to distribute couriers between depots based on shipment volume at the depots. Conditions:

  • There are several depots.

  • Couriers start from home or from parking spots.

  • Vehicle fleet is common for all depots.

This scenario can be used both when there's no need to visit additional depots and when delivery to a single point may require visiting additional depots.

How to implement this scenario

  1. Pickup & delivery pairs

    For each delivery point, set the coordinates of the depot to ship from inpickup and specify the delivery point indelivery .

  2. Arbitrary start and end points of the route

    Set the start and end point of the courier route using additional garage points. At the same time, set return_to_depot and visit_depot_at_start = false (learn more in Starting from a point other than the depot and Return to an arbitrary point at the end of the route).

  3. Nominal depot

    In the depot object, specify the nominal depot (for example, the coordinates of any depot). This depot won't be included in planning, but it can't be omitted.

Tip.

Use multiple pickup in this scenario: fill in the same delivery_to for several pickup at different depots.

Diagram

Example

In the example, several depots and multiple pickup are used. All vehicles have their own garage points set as start_at and finish_at. The main depot isn't included in planning.

API request (JSON) API response View on map

Delivery to one out of multiple points

Situations to use this in

Use this scenario in cases where cargo can be delivered to one of several possible points and you need to choose the optimal one:

  • Collecting medical tests from clients' homes to take them to the nearest lab.

  • Collecting garbage or scrap metal to take it to the nearest disposal site.

  • Picking up a parcel from a client to send it via a third-party transport company, which is why you need to take it to the nearest receiving terminal.

  • Courier delivery. You need to plan a meeting between a regular courier and a courier with a fixed route that collects urgent shipments from regular couriers.

How to implement this scenario

Implement the delivery to one of multiple possible points scenario using the delivery_to_any parameter.

Diagram

Example

In this example, a set of pickup orders is implemented. For each order, several identical points are specified indelivery_to_any. After collecting orders, the courier will take them to the nearest drop_off point at the end of their shift. For the first courier, it's “Lab 3”, and for the second one, “ Lab 4” .

API request (JSON) API response View on map

Receiving cargo at one of the possible points

Situations to use this in

Use this scenario in situations where certain cargo can be received at several points and you need to choose the optimal one among them. For example:

  • The goods to be delivered are located at different points (for example, in one of the grocery stores or pharmacies).

  • The cargo can be received at one of the terminals of a third-party transport company.

  • It's necessary to plan a meeting between a regular courier and a courier with a fixed route that takes urgent shipments to regular couriers.

How to implement this scenario

Learn more in the description of the pickup_from_any parameter.

Diagram

Example

In this example, there are 2 delivery orders with pickup_from_any set to true. 2 pickup orders are associated with each of these orders.

Please note that all pickup orders and the linked delivery order must be the same weight.

API request (JSON) API response View on map

Planning multiple runs from the depot for one courier

Situations to use this in

  • The shipment volume exceeds available load capacity

    In this case, all or some of the vehicles must make more than one run to ship all the orders.

  • It's impossible to collect all orders by the time of shipment

    Sometimes depot capacity doesn't allow you to collect all orders by the time shipment starts, but delivery must start immediately to ensure that order windows are met. In this case, couriers will make their first run not fully loaded, so that they can deliver the orders with earlier delivery windows on time. Meanwhile, the depot will collect orders with later delivery windows, which will be delivered during future runs.

How to implement this scenario

  • To enable multiple runs, use the max_runs parameter (for more information, see Multiple vehicle runs per day).

  • To take into account that not all orders will be collected by the time shipment starts, use the depot_ready_time parameter (for more information, see Order ready time).

Diagram

Example 1

In this example, the total weight of the three orders (3000 kg) exceeds the total load capacity of two vehicles (2500 kg). Courier 2 will make two runs (max_runs), delivering the third order during the second run.

API request (JSON) API response View on map

Example 2

In this example, the courier will first deliver the earlier orders (time_window), depot_ready_time determines if they're ready or not. The max_runs parameter will allow them to return to the depot to collect the later orders.

API request (JSON) API response View on map

Additional planning of the route

Situations to use this in

Use this scenario when some orders are already distributed to vehicles and you want to maintain this distribution.

The following additional planning situations are possible:

  1. Some of the orders are already allocated to routes, and there are unallocated delivery orders, but the vehicles haven't departed from the depot yet .
  2. Additional orders are received (e.g., orders of the type pickup ), but the vehicles have already departed from the depot .

Meanwhile, in both cases, you need to preserve allocation of the earlier planned orders and additionally allocate new (“unallocated”) orders to vehicles with vacant timeslots or cargo space.

Generally speaking, additional planning is needed when you can't solve the routing task completely in one iteration, so you run it stepwise, passing the previous iteration results to the next planning.

How to implement this scenario

In each case, it's important to know whether to preserve the sequence of earlier allocated orders. To preserve the order sequence, use the vehicles.visited_locations property. Otherwise, use the vehicles.planned_route property.

Case 1 (vehicles haven't departed yet)

To generate a request, you need to know:

  • Already allocated orders for each vehicle.

  • New orders received since the last planning.

In the new request for additional planning per each vehicle, use theplanned_route field (visited_locations) to specify the IDs (locations or id) for already allocated orders (from the previous planning iteration).

Case 2 (vehicles already departed)

To generate a request, you need to know:

  • Already allocated orders for each vehicle.

  • Location of each vehicle at the time of additional planning (this may also be the last delivered or the next order in the sequence).

  • List of already completed orders.

  • New orders received since the last planning.

In the new request for additional planning:

  1. For each vehicle, use the planned_route field (visited_locations) to specify the IDs (locations or id) of already allocated orders (from the previous planning iteration), but not completed at the time of additional planning.
  2. Add “dummy” orders to the list: these orders should correspond to the current location points for each vehicle. You may skip this step if the current location point is the last order delivered or the next order in the sequence.
  3. For each vehicle, specify the ID of its current location and the time of departure from it in the first element in the visited_locations field.
    Note.

    For previously unused vehicles, set the correct departure parameters: either shift the start time of the shift or specify the current depot location in visited_locations.

  4. From the list of orders, delete the already completed orders (taking note of p. 2: If the latest delivered order is used as the current location point, don't delete it).

Notes

The initial allocation subject to additional planning must be done so that the vehicles have free timeslots/cargo space (otherwise, the additional orders won't fit in). To do this, decrease the vehicle shift time using the balanced groups option (balanced_groups) or limited capacity (specify a lower capacity for the vehicles).

Attention.

All the additional restrictions introduced at the first iteration to artificially underload the vehicles have to be disabled before the additional planning.

Use the tag functionality if you want to prevent the selected vehicles from additional orders. For more information, see Vehicle tags.

Basic task

The task includes 70 orders and 9 available couriers, the balanced groups option is used balanced_groups.

Get 5 couriers in the solution.

Planning result:

Courier Number of orders Order sequence
Courier 1 14 45, 31, 58, 24, 52, 54, 39, 47, 19, 30, 43, 28, 29, 49
Courier 3 17 18, 37, 38, 17, 2, 59, 34, 35, 26, 32, 20, 69, 5, 50, 15, 21, 6
Courier 4 14 44, 16, 53, 70, 27, 64, 65, 40, 60, 4, 63, 33, 56, 48
Courier 6 11 46, 11, 1, 10, 8, 41, 14, 12, 13, 22, 9
Courier 7 14 3, 23, 51, 55, 42, 36, 68, 66, 61, 25, 7, 67, 57, 62
Courier Number of orders Order sequence
Courier 1 14 45, 31, 58, 24, 52, 54, 39, 47, 19, 30, 43, 28, 29, 49
Courier 3 17 18, 37, 38, 17, 2, 59, 34, 35, 26, 32, 20, 69, 5, 50, 15, 21, 6
Courier 4 14 44, 16, 53, 70, 27, 64, 65, 40, 60, 4, 63, 33, 56, 48
Courier 6 11 46, 11, 1, 10, 8, 41, 14, 12, 13, 22, 9
Courier 7 14 3, 23, 51, 55, 42, 36, 68, 66, 61, 25, 7, 67, 57, 62

API request (JSON) API response View on map

Now let's look at the methods of additional planning for the basic task.

Example 1

Additional planning at the depot, changing the order sequence in the routes.

In the request, enter 110 orders (40 of them are new with regards to the basic task) and 9 available couriers. For 5 couriers, specify the allocation from the basic task in planned_route. Also, use the balanced group option (balanced_groups).

Get 7 couriers in the solution.

Planning result:

Courier Number of orders Sequence of orders relative to the basic task
Courier 1 16

2 orders added:

45, 31, 58, 24, 52, 87, 54, 39, 100, 47, 19, 30, 43, 28, 29, 49

Courier 2 14 New route
Courier 3 18

1 order added:

18, 37, 38, 17, 2, 59, 34, 35, 26, 32, 20, 69, 104, 5, 50, 15, 21, 6

Courier 4 19

5 orders added, sequence greatly changed:

27, 64, 65, 40, 99, 60, 4, 53, 70, 44, 16, 102, 63, 33, 85, 56, 88, 48, 84

Courier 6 14

3 orders added, sequence changed:

46, 80, 11, 71, 12, 10, 8, 1, 83, 14, 41, 13, 22, 9

Courier 7 16

2 orders added, sequence slightly changed:

3, 23, 79, 51, 42, 55, 36, 68, 66, 61, 25, 7, 67, 108, 57, 62

Courier 8 13 New route
Courier Number of orders Sequence of orders relative to the basic task
Courier 1 16

2 orders added:

45, 31, 58, 24, 52, 87, 54, 39, 100, 47, 19, 30, 43, 28, 29, 49

Courier 2 14 New route
Courier 3 18

1 order added:

18, 37, 38, 17, 2, 59, 34, 35, 26, 32, 20, 69, 104, 5, 50, 15, 21, 6

Courier 4 19

5 orders added, sequence greatly changed:

27, 64, 65, 40, 99, 60, 4, 53, 70, 44, 16, 102, 63, 33, 85, 56, 88, 48, 84

Courier 6 14

3 orders added, sequence changed:

46, 80, 11, 71, 12, 10, 8, 1, 83, 14, 41, 13, 22, 9

Courier 7 16

2 orders added, sequence slightly changed:

3, 23, 79, 51, 42, 55, 36, 68, 66, 61, 25, 7, 67, 108, 57, 62

Courier 8 13 New route
Note.

Orders planned in the basic task are still assigned to the same couriers, but:

  • For the couriers from the basic solution, new orders are added among other points on the route.

  • For the couriers from the basic solution, the order sequence planned earlier is changed.

  • 2 new routes are added.

API request (JSON) API response View on map

Example 2

Additional planning at the depot, without changing the order sequence in the routes.

In the request, enter 110 orders (40 of them are new with regards to the basic task) and 9 available couriers. For 5 couriers, specify the allocation from the basic task in visited_locations. Also, use the balanced group option (balanced_groups).

Get 7 couriers in the solution.

Planning result:

Courier Number of orders Sequence of orders relative to the basic task
Courier 1 17

3 orders added:

45, 31, 58, 24, 52, 54, 39, 47, 19, 30, 43, 28, 29, 49, 106, 93, 101

Courier 3 17

Route unchanged:

18, 37, 38, 17, 2, 59, 34, 35, 26, 32, 20, 69, 5, 50, 15, 21, 6

Courier 4 18

4 orders added:

44, 16, 53, 70, 27, 64, 65, 40, 60, 4, 63, 33, 56, 48, 84, 96, 85, 88

Courier 6 14

3 orders added:

46, 11, 1, 10, 8, 41, 14, 12, 13, 22, 9, 80, 71, 79

Courier 7 15

1 order added:

3, 23, 51, 55, 42, 36, 68, 66, 61, 25, 7, 67, 57, 62, 108

Courier 8 15 New route
Courier 9 14 New route
Courier Number of orders Sequence of orders relative to the basic task
Courier 1 17

3 orders added:

45, 31, 58, 24, 52, 54, 39, 47, 19, 30, 43, 28, 29, 49, 106, 93, 101

Courier 3 17

Route unchanged:

18, 37, 38, 17, 2, 59, 34, 35, 26, 32, 20, 69, 5, 50, 15, 21, 6

Courier 4 18

4 orders added:

44, 16, 53, 70, 27, 64, 65, 40, 60, 4, 63, 33, 56, 48, 84, 96, 85, 88

Courier 6 14

3 orders added:

46, 11, 1, 10, 8, 41, 14, 12, 13, 22, 9, 80, 71, 79

Courier 7 15

1 order added:

3, 23, 51, 55, 42, 36, 68, 66, 61, 25, 7, 67, 57, 62, 108

Courier 8 15 New route
Courier 9 14 New route
Note.

Orders planned in the basic task are still assigned to the same couriers, but:

  • For the couriers from the basic solution, new orders were added to the end of the route.

  • 2 new routes are added.

API request (JSON) API response View on map

Example 3

Additional planning when couriers have already departed from the depot (without changing the sequence of orders in the routes).

At the time of planning, assume that 15 orders were delivered (3 orders for each of the 5 couriers from the basic task), and delete them from the additional planning task.

In total, enter 100 orders in the request (40 new orders, 55 non-delivered orders from the basic task, and 5 courier start points), and 9 available couriers. For 5 couriers, specify the allocation from the basic task in visited_locations. Also, use the balanced group option (balanced_groups).

Get 8 couriers in the solution (3 of them are new couriers who start from the depot).

Planning result:

Courier Number of orders* Sequence of orders relative to the basic task
Courier 1 12

1 order added:

45, 31, 58 (completed orders), 1001 (start point), 24, 52, 54, 39, 47, 19, 30, 43, 28, 29, 49, 101

Courier 2 10 New route
Courier 3 14

Route unchanged:

18, 37, 38 (completed orders), 1003 (start point), 17, 2, 59, 34, 35, 26, 32, 20, 69, 5, 50, 15, 21, 6

Courier 4 13

2 orders added:

44, 16, 53 (completed orders), 1004 (start point), 70, 27, 64, 65, 40, 60, 4, 63, 33, 56, 48, 84, 88

Courier 6 11

3 orders added:

46, 11, 1 (completed orders), 1006 (start point), 10, 8, 41, 14, 12, 13, 22, 9, 80, 71, 79

Courier 7 12

1 order added:

3, 23, 51 (completed orders), 1007 (start point), 55, 42, 36, 68, 66, 61, 25, 7, 67, 57, 62, 108

Courier 8 11 New route
Courier 9 12 New route
Courier Number of orders* Sequence of orders relative to the basic task
Courier 1 12

1 order added:

45, 31, 58 (completed orders), 1001 (start point), 24, 52, 54, 39, 47, 19, 30, 43, 28, 29, 49, 101

Courier 2 10 New route
Courier 3 14

Route unchanged:

18, 37, 38 (completed orders), 1003 (start point), 17, 2, 59, 34, 35, 26, 32, 20, 69, 5, 50, 15, 21, 6

Courier 4 13

2 orders added:

44, 16, 53 (completed orders), 1004 (start point), 70, 27, 64, 65, 40, 60, 4, 63, 33, 56, 48, 84, 88

Courier 6 11

3 orders added:

46, 11, 1 (completed orders), 1006 (start point), 10, 8, 41, 14, 12, 13, 22, 9, 80, 71, 79

Courier 7 12

1 order added:

3, 23, 51 (completed orders), 1007 (start point), 55, 42, 36, 68, 66, 61, 25, 7, 67, 57, 62, 108

Courier 8 11 New route
Courier 9 12 New route

*: without the completed orders and start point.

Note.

In this solution, all the couriers start at 11:00, and new orders are added to the end of the route.

API request (JSON) API response View on map

Cross-docking

A cross-dock is an intermediate depot where transloading, re-consolidation, or re-loading of goods is carried out. Specify the crossdock value in the type field for such depots.

Cross-docking can be used for some orders to ensure the speed of delivery and reduce transport costs: orders are taken to a cross-dock closer to distant locations in advance. For example, a depot is located north of the city, and delivery is carried out in the daytime. In this case, to deliver orders to the southern part of the city, a cross-dock is created in the south, where some orders are delivered at night by large vehicles.

Orders aren't stored at cross-docks. Instead, one or more vehicles bring the orders, and then one or more vehicles pick them up and deliver them to clients. At the moment, different vehicles must transport orders to and from the cross-dock.

For vehicles, the restriction on working with cross-docks is set using the crossdock_mode parameter. It can take the following values:

  • allow: The vehicle can take orders both to clients and to an intermediate depot (default value).
  • deny: The vehicle can only take orders to clients.
  • mandatory: The vehicle can only take orders to an intermediate depot.

To specify which depot or cross-dock the vehicle starts from, use the vehicle.depot_id field.

For orders, the crossdock_mode parameter is also set with the following values:

  • allow: The order can be delivered both directly from the depot and via an intermediate depot (default value).
  • deny: The order can only be delivered directly from the depot.
  • mandatory: The order can only be delivered via an intermediate depot.

To specify which depot the order is stored at or via which cross-dock it must be delivered, use the location.depot_id field. If multiple depots and cross-docks are specified, the order can be picked up from any of them.

For pickup orders, you can set the may_drop_in_crossdock parameter with the following values:

  • true: The order can be left in the cross-dock (default value).
  • false: The order must be delivered to a regular depot.

The may_drop_in_crossdock parameter can only be used in the Delivery to one out of multiple points scenario. If there are pickup&delivery pairs with the possibility of transloading at a cross-dock, use the Pickup & delivery via a cross-dock scenario.

Restriction. The courier first delivers delivery orders to the cross-dock and only after that picks up pickup orders from the cross-dock.

Handling time

For orders delivered via cross-docking, location.crossdock_service_duration_s is taken into account. When a vehicle arrives from a regular depot to a cross-dock, the handling time for it is calculated using the formula:

depot.service_duration_s + Total{ location.crossdock_service_duration_s} for all orders that the vehicle brought.

When using cross-docking, it's useful to have a time buffer depot.crossdock_safety_waiting_duration_s — the minimum amount of time that must pass between unloading an order at the cross-dock and when it can be picked up for delivery to the client. This buffer is necessary so that the potential delay of the first vehicle (carrying orders to the cross-dock) won't affect the routes of vehicles that pick up orders from the cross-dock.

Diagram

Example 1

5 couriers and 6 orders that need to be delivered from 2 depots and partially via a cross-dock. The depots are located in the west of Moscow, and the cross-dock is in the east. Orders 1, 2, and 3 are located closer to depot 1 and are delivered from the depot. Orders 4, 5, and 6 are in the east and are delivered via a cross-dock.

Planning result:

Courier Courier characteristics Route
Courier 1 Starts from depot 1. Isn't allowed to take orders to the cross-dock.

Picks up orders 1, 2, and 3 from depot 1 and delivers them to clients.

Courier 2 Starts from depot 2. All routes are allowed. Picks up orders 4 and 6 from depot 2 and takes them to the cross-dock.
Courier 3 Starts from depot 1. Can only take orders to the cross-dock.

Picks up order 5 from depot 1 and takes it to the cross-dock.

Courier 4 Starts from the cross-dock.

Picks up orders 5 and 6 from the cross-dock and takes them to clients.

Courier 5 Starts from the cross-dock.

Picks up order 4 from the cross-dock and takes it to the client.

Courier Courier characteristics Route
Courier 1 Starts from depot 1. Isn't allowed to take orders to the cross-dock.

Picks up orders 1, 2, and 3 from depot 1 and delivers them to clients.

Courier 2 Starts from depot 2. All routes are allowed. Picks up orders 4 and 6 from depot 2 and takes them to the cross-dock.
Courier 3 Starts from depot 1. Can only take orders to the cross-dock.

Picks up order 5 from depot 1 and takes it to the cross-dock.

Courier 4 Starts from the cross-dock.

Picks up orders 5 and 6 from the cross-dock and takes them to clients.

Courier 5 Starts from the cross-dock.

Picks up order 4 from the cross-dock and takes it to the client.

API request (JSON) API response View on map

Example 2

The planning task has 2 couriers, 1 depot in the south of Moscow, and a cross-dock in the east. The following conditions are set for orders:

Order Order type Where it is located Where it is delivered to Via a cross-dock You can leave it at the cross-dock
1 delivery At the depot To the client Yes -
2 pickup From the client To the cross-dock No Yes
3 pickup From the client To the cross-dock No Yes
4 pickup From the client To the depot Yes No
Order Order type Where it is located Where it is delivered to Via a cross-dock You can leave it at the cross-dock
1 delivery At the depot To the client Yes -
2 pickup From the client To the cross-dock No Yes
3 pickup From the client To the cross-dock No Yes
4 pickup From the client To the depot Yes No

Planning result:

Courier Courier characteristics Route
Courier 1 Starts from depot 1. Can only take orders to the cross-dock. Picks up order 1 from the depot and takes it to the cross-dock. Picks up order 4 from the cross-dock and takes it to the depot.
Courier 2 Starts from the cross-dock. Picks up order 1 from the cross-dock, picks up orders 2, 3, and 4 from clients, delivers order 1 to the client, and delivers orders 2, 3, and 4 to the cross-dock.
Courier Courier characteristics Route
Courier 1 Starts from depot 1. Can only take orders to the cross-dock. Picks up order 1 from the depot and takes it to the cross-dock. Picks up order 4 from the cross-dock and takes it to the depot.
Courier 2 Starts from the cross-dock. Picks up order 1 from the cross-dock, picks up orders 2, 3, and 4 from clients, delivers order 1 to the client, and delivers orders 2, 3, and 4 to the cross-dock.

API request (JSON) API response View on map

Example 3

The same depots and couriers as in example 2. The following conditions are set for orders:

Order Order type Where it is located Where it is delivered to Via a cross-dock You can leave it at the cross-dock
1 delivery At the depot To the client Yes -
2 pickup From the client To drop_off or drop_off_2 (delivery_to_any) No Yes
3 pickup From the client To the cross-dock No Yes
4 pickup From the client To the depot Yes No
Order Order type Where it is located Where it is delivered to Via a cross-dock You can leave it at the cross-dock
1 delivery At the depot To the client Yes -
2 pickup From the client To drop_off or drop_off_2 (delivery_to_any) No Yes
3 pickup From the client To the cross-dock No Yes
4 pickup From the client To the depot Yes No

Planning result:

Courier Courier characteristics Route
Courier 1 Starts from depot 1. Can only take orders to the cross-dock. Picks up order 1 from the depot and takes it to the cross-dock. Picks up order 4 from the cross-dock and takes it to the depot.
Courier 2 Starts from the cross-dock. Picks up order 1 from the cross-dock, picks up order 2 from the client, delivers order 1 to the client, picks up orders 3 and 4 from clients, delivers order 2 to drop_off_2, takes orders 3 and 4 to the cross-dock.
Courier Courier characteristics Route
Courier 1 Starts from depot 1. Can only take orders to the cross-dock. Picks up order 1 from the depot and takes it to the cross-dock. Picks up order 4 from the cross-dock and takes it to the depot.
Courier 2 Starts from the cross-dock. Picks up order 1 from the cross-dock, picks up order 2 from the client, delivers order 1 to the client, picks up orders 3 and 4 from clients, delivers order 2 to drop_off_2, takes orders 3 and 4 to the cross-dock.

API request (JSON) API response View on map

Planning without considering the delivery distance to the cross-dock

Situations to use this in

Use this option if there is no need to take into account the delivery distance from the main depot to the cross-dock.

How to implement this scenario

This scenario is similar to Delivery from one of several depots, and it can be implemented the same way.

Attention.

Unlike the cross-docking scenario described above, delivery of orders to the cross-dock isn't included in the routes in this scenario. When planning, it's assumed that any order can be taken to a cross-dock, and you need to choose which orders are more profitable to ship from there. You also need to know in advance which vehicles start from the main depot and which ones start from a cross-docking platform.

Diagram

Example

The 60 delivery points are orders to deliver. The garage point is a cross-dock. One courier must start the route from the depot, and the other one must start from the cross-dock.

API request (JSON) API response View on map

Pickup & delivery via a cross-dock

Situations to use this in

This scenario is used if the orders that need to be delivered from the cross-dock must be picked up from pickup points in advance.

How to implement this scenario

Set time limits for routes to bring orders to the cross-dock and then deliver them to clients.

  • Pickup and delivery by different vehicles

    Split delivery to and from the cross-dock into different planning runs. You will get one planning according to the Cargo collection to the depot scenario and the second according to the Delivery from a single depot scenario.

    Example

    Cross-docking with two 2 different planning runs: pickup and delivery.

    1. The first part is the pickup. During the morning shift, one vehicle collects orders from different addresses and returns to the depot.

      API request (JSON) API response View on map

    2. The second part is the delivery. During the day shift, another vehicle collects orders from the depot and delivers them to clients.

      API request (JSON) API response View on map

  • Collection and delivery by a single vehicle

    Set a time limit for order collection and delivery.

    1. For orders that need to be collected at a cross-dock:
    2. For orders that need to be delivered from a cross-dock:

    Between the delivery_deadline and depot_ready_time parameter values, there must be a window to allow for cross-docking operations. For example, collect the cargo before 13:00 and start delivery at 14:00.

    Example

    1 courier, 10 pickup orders, and 10 delivery orders. The orders are not linked. All pickup orders need to be delivered to the depot before 13:00, and all delivery orders can be picked up from the depot beginning at 14:00. For the courier to carry out the orders in 2 runs, vehicle.max_runs = 2 is specified.

    API request (JSON) API response View on map

Diagram

Delivery with vehicle parking before the walking part of the route

Situations to use this in

The scenario is used when there are several closely located orders along the route. The courier can arrive by vehicle, park, and deliver orders on foot. There may be several such walking parts on the route.

How to implement this scenario

Set the parameters:

  • vehicle.walking_courier.capacity: Carrying capacity of the courier in units. This parameter determines the maximum number of units a courier can carry. To use the parameter, additionally specify the number of units for the order using the location.shipment_size parameter.

    If the courier needs to carry more units than specified in the vehicle.walking_courier.capacity parameter, the algorithm will plan the route where the vehicle will be parked several times.

    For example, if the courier needs to visit 10 points during the walking delivery, and the parameter is vehicle.walking_courier.capacity.units = 5, the courier will deliver 5 units, repark the vehicle, and deliver the remaining 5 units.

    Note.

    RouteQ supports scenarios where only one courier can leave the vehicle and deliver orders on foot.

  • vehicle.walking_courier.cost.hour and/or vehicle.walking_courier.cost.km: The cost of walking delivery per hour and per kilometer. The cost of walking delivery is calculated the same way as the vehicle or courier cost.
  • vehicle.walking_courier.max_walking_edge_distance_m: The maximum distance between two points on walking parts of the route.
  • location.parking_service_duration_s: The amount of time that the courier spends parking the vehicle.
    Note.

    For the walking and transit routing modes, the location.parking_service_duration_s parameter isn't included in the calculations of the time spent.

    For other modes, the time specified in the location.parking_service_duration_s parameter will be taken into account only once: before the start of the walking part of the route.

Diagram

Example

The route includes 10 orders. Some orders have the same delivery address:

  • Order 1 and order 3.
  • Order 5, order 7, and order 9.
  • Order 8 and order 10.

To deliver these orders, the courier parks the vehicle near the building and delivers the orders on foot. To deliver the remaining orders, the courier travels by vehicle.

API request (JSON) API response View on map

Contact support