Possible logistic scenarios

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

This is the default scenario when cargo is collected from your clients to be delivered to the depot. For examples, this 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 couriers must return to the depot at the end of the day (see Returning to a 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 courier 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 couriers return to the depot at the end of the day. The algorithm chooses which ones must return. For couriers, the return_to_depot = false option is used, and for pickup orders, you specify whether it's mandatory to return to the depot in the current route pickup_must_reach_depot = true or set up delivery_deadline, which is the time of order delivery to the depot.

   If the order is linked to a depot (one or more depots are given in the depot_id field), the pickup order will be delivered to one of these depots in the current route, regardless of the pickup_must_reach_depot value.

Schemes

• Cargo delivery to the depot.

  
• Delivery of cargo to one of several depots.

  

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 same as example 1. One of the vehicles has return_to_depot set to false. 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

The same as example 1, but different pickup points are selected. For all vehicles, return_to_depot = false, and delivery_deadline is specified for the cargo 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

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.

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.

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 be different 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 be different 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 be different 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 be different for different couriers.

  

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.

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

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

When planning, specify multiple depots and which depot each courier is assigned to (which depots they can start from and visit). For more information, see 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.

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 built two routes:

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

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

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 scenario "delivery to one of multiple possible locations" using the delivery_to_any parameter.

You can see where the order was delivered in the API response: in the delivered_orders field for depots or drop_off orders.

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. This will be “Laboratory 4” and “Laboratory 2” for the first and second couriers, respectively. In the API response, you can see the orders delivered to these locations in the delivered_orders field.

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

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

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 Time when the order is ready at the depot).

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

Situations to use this in

Use this scenario if the initial list of orders has already been assigned to couriers, they have started their routes, and you need to assign orders that came in for delivery later.

This scenario can only be implemented using API requests. If you want to do additional route planning in the routing workspace, use the Additional route planning (with restrictions) scenario.

How to implement this scenario

In the additional planning request, use the locations object to pass in the general list of orders that includes both the already planned orders and orders that require additional planning.

Also include the initial_routes object with data on originally planned runs in the request. This data can be copied from the result.routes object in the API response for the first planning task. For each run, pass in the following objects:

• route: Array of stops in the run.
• run_number: Run number.
• shift: Courier shift.
• vehicle_id: Courier ID.

Order sequence

If a previously planned run needs to be saved without any changes, set immutable = true for it in the initial_routes object. If the order of stops in a run shouldn't change, set fixed_order = true.

If you only want to prohibit changes on a part of a run (a sequence of consecutive stops), set node.value.fixed_position = true for each of these stops.

To have an order delivered by the courier that was originally planned, set fixed_vehicle = true for that order. If you want an order to remain in the same shift, set fixed_shift = true, and to keep it in the same run, set fixed_run = true.

If none of these attributes is set, new orders may get mixed in with the existing ones in a random order.

Loaded orders

The IDs of the orders that were loaded into a vehicle before it departed a depot need to be listed in the loaded_orders field for node locations with the depot type. If the new order is not on the loaded_orders list, an additional visit to the depot for loading this order is planned for the courier. If loaded_orders not set, all orders were considered loaded at the depot.

An order can be loaded into a vehicle during the initial planning, but during additional planning it may be set as undistributed. In this case, the order will still take up space in the vehicle. To have the algorithm take this into account, set keep_in_vehicle = true for the order.

Order visit time

If at the time of additional planning some of the orders have already been delivered, their times are indicated in the following fields:

• actual_arrival_time_s: Arrival at the order location.
• actual_service_start_time_s: Order handling start time.
• actual_departure_time_s: Departure from the order location.

You can also use the arrival_time_s and departure_time_s fields. They can only be set for either all or none of the run locations. Arrival and departure times must be unique for all orders, which is why we don't recommend including multi-orders in additional planning.

If a courier's shift starts later than the visit time of their first order, an error will occur during additional planning.

Courier's current location

If a courier has already started a route, additional planning should take their current location into account.

A courier's current location is set in a separate node location with type = courier. In the value.location_id field, specify either the ID of the last order visited by the courier or the ID of the location with the courier's coordinates.

The time the courier spends at this location goes in the actual_departure_time_s field.

Example

During the first planning, the courier picks up 10 orders from the depot and delivers them.

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

During additional planning, 4 more orders are added. By the time additional planning starts, the courier has already delivered the first two orders. To indicate this, the initial_routes object for the depot and the first two orders has fixed_position = true. The new solution now has a different delivery sequence for the remaining orders.

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

Situations to use this in

Use this scenario when some orders have already been assigned to vehicles, and you want to maintain this distribution while adding new orders to the routes.

This scenario has a number of restrictions when it comes to fixed parts of routes. If you are doing additional planning using API requests, we recommend using the Additional route planning scenario.

The following additional planning situations are possible:

1. Some of the orders are already assigned to routes, and there are undistributed delivery orders, but the vehicles haven't left the depot yet.

2. Additional orders are received (for example, pickup-type orders), but the vehicles have already left the depot.

In both cases, you need to maintain the earlier planned orders as well as distribute new (“undistributed”) 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 keep the current sequence of assigned orders. To keep the order sequence, use the vehicles.visited_locations field. Otherwise, use the vehicles.planned_route field. In the lists, you can specify orders and depots for reloading that the courier needs to visit when traveling along the route.

Case 1 (vehicles haven't departed yet)

To generate a request, you need to know:

• What orders were already assigned to each vehicle.

• What new orders have been received since the last planning.

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

Case 2 (vehicles already departed)

To generate a request, you need to know:

• What orders were already assigned to 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.

• What new orders have been 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 assigned 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 can skip this step if the current location 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.

   To set the time of departure from the location, use the planned_route.start_time parameter (or visited_locations.N.time).

   Possible time formats:

   • relative: [D.]HH[:MM[:SS]], where D is the date shift relative to the start date of the route.
   • absolute: ISO 8601 format (for example, 2018-09-06T10:15:00+03:00).

   Learn more about time formats

   Example

   Here, departure from route location 1001 will be scheduled for 10:20.

   "visited_locations": [
       {
         "id": "1001",
         "shift_id": "1",
         "time": "10:20"
       },
       ...
   ]

   Note.

   For previously unused vehicles, set the correct departure parameters: either move 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 ones (taking note of item 2: if the last delivered order is used as the current location, don't delete it).

Notes

The initial distribution (subject to additional planning) must ensure 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).

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:

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 compared 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:

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 compared to the basic task) and 9 available couriers. For 5 couriers, specify the assignment from the basic task in  visited_locations. Also, use the balanced group option (balanced_groups).

Get 7 couriers in the solution.

Planning result:

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 assignment 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:

*: without the completed orders and start point.

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

A cross-dock is a depot for the transshipment, reconsolidation, or reloading of goods. 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 a cross-dock (default value).
• deny: The vehicle can only take orders to clients.
• mandatory: The vehicle can only take orders to a cross-dock.

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 a cross-dock (default value).
• deny: The order can only be delivered directly from the depot.
• mandatory: The order can only be delivered via a cross-dock.

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 of multiple locations 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.

Handling time

For orders delivered via a cross-dock, 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 (by default, 3600 seconds, or 1 hour). 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

4 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 in the west and are delivered from depots. Orders 4, 5, and 6 are in the east and are delivered via a cross-dock.

Planning result:

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:

Planning result:

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:

Planning result:

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

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. If it's not possible to carry all orders in one run, the courier makes several runs. At the start of each run, the courier takes some of the orders, delivers them, and then gets back to the vehicle and takes the next batch of the orders.

The route may include a few walking parts.

How to implement this scenario

Set the parameters:

• location.parking_service_duration_s: The amount of time that the courier spends parking the vehicle.

  Note.

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

  For other transportation methods, 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.

• vehicle.walking_courier.capacity.units: The maximum number of units that the courier can carry. To use this feature, 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.units parameter, the algorithm can build the route so that the courier makes multiple runs. For example, if the courier needs to visit 10 locations during the walking delivery, and vehicle.walking_courier.capacity.units = 5, the courier delivers 5 units first, goes back to the vehicle, and then picks up the remaining 5 units.

  Note.

  RouteQ supports scenarios where only one courier leaves the vehicle and delivers 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.restrictions: Restrictions for walking parts of routes:

  • max_walking_edge_distance_m.value and max_walking_edge_distance_m.penalty: The maximum distance (in meters) between two points on walking parts of the route and the penalty for violating the restriction.
  • max_parking_walking_distance_m.value and max_parking_walking_distance_m.penalty: The maximum walking distance (in meters) in a parking session and the penalty for violating the restriction.
  • max_parking_duration_s.value and max_parking_duration_s.penalty: The maximum duration (in seconds) of a parking session and the penalty for violating the restriction.
  • close_locations: Array of restrictions for nearby order locations:

    • duration_till_service_s.value and duration_till_service_s.penalty: The maximum time (in seconds) between handling two nearby orders and the penalty for violating the restriction.
    • distance_till_service_m.value and distance_till_service_m.penalty: The maximum distance (in meters) walked between two nearby orders and the penalty for violating the restriction.
    • search_radius_m: The distance between two orders, which are considered nearby and subject to restrictions.
    • soft_search_radius_m: If the value of this parameter exceeds the value of the corresponding search_radius_m , orders at a distance from search_radius_m to soft_search_radius_m are also subject to restrictions, but their size decreases linearly depending on the distance. For example, at the distance (search_radius_m + soft_search_radius_m) / 2, a restriction of a weight of 0.5 applies.

    Example of using the settings of nearby orders

    {
    ...
        "walking_courier": {
            ...
            "restrictions": {
                "close_locations": [
                    {
                        "search_radius_m": 400,
                        "soft_search_radius_m": 500,
                        "distance_till_service_m": {
                            "penalty": 0.02,
                            "value": 1500
                        }
                    },
                    {
                        "search_radius_m": 100,
                        "soft_search_radius_m": 160,
                        "duration_till_service_s": {
                            "penalty": 0.02,
                            "value": 1500
                        }
                    }   
                ],
                ...
            }
            ...
        },
    ...
    }

    In the example above, the first restriction is that orders up to 400 meters away from each other must be handled within the next 1500 meters of movement. The penalty for violating the restriction is 0.02 for every meter. For orders 400 to 500 meters away from each other, this restriction also applies, but it decreases linearly depending on the distance. For example, for an order 430 meters away, a penalty equal to 0.7 of the main penalty is applied.

    The second restriction is similar to the first one, but it sets the time between handling orders. Orders within a radius of 100 meters must be handled within 25 minutes with a 0.02 penalty for each second over. Orders 100 to 160 meters away are subject to the restriction, which decreases linearly as the distance grows.

To balance the cost of visiting orders on foot and vehicle, use options.average_projection_walking_part_distance_m. This option sets the average walking distance from the road to the order. When the option is used, for each visit to an order by vehicle, the courier is subject to twice the penalty cost for walking.

For example, if average_projection_walking_part_distance_m = 15, the cost of 30 meters of the walking route is added to the cost of each visit. You can use this setting to compensate for the cost of walking part of the way when using the driving transportation method compared to the same distance with the walking transportation method.

Diagram

Example 1

The route includes 10 orders. Some orders are near each other:

• Orders 1, 2, 3, and 4.
• Orders 5, 7, and 9.
• Orders 8 and 10.

Because the cost of delivery on foot is less than the cost of driving, the courier parks the vehicle and delivers nearby orders on foot. To deliver the remaining orders, the courier travels by vehicle.

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

Example 2

The same as example 1, but vehicle.walking_courier.capacity.units = 2. To deliver orders located close to each other, the courier parks the vehicle and delivers no more than two units per run.

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

Situations to use this in

By default, only a tractor (truck) without a trailer can arrive at the order location. Use this scenario if the order location is available for trucks with a trailer. For settings that affect trucks with a trailer, see Trailers.

How to implement this scenario

Set the accessibility of a location for a tractor with a trailer in the location.allow_trailers field. The default is location.allow_trailers = false, a non-accessible location where only a tractor without a trailer can arrive. To implement a scenario with an accessible location, set location.allow_trailers = true. In this case, the location is accessible for a tractor with a trailer.

Types of orders for tractors with trailers:

• anchor: Location where you can leave a trailer for a long period of time and perform a rolling.

• parking: Point where you can leave a trailer only while unloading an order.

You can arrive at the location with the anchor type with a trailer, leave it for a few hours, and perform rolling. This order must have a unique id. If you need to deliver cargo to this point, create another order with the delivery type (see Order type).

The number of vehicles (tractor and trailer couplings) that the anchor point can serve is unlimited by default. If necessary, specify the maximum number of vehicles that can simultaneously be at the anchor location in the max_total_vehicles parameter.

You can leave a trailer at the location with the parking type only while unloading one order in a non-accessible store.

When performing the planning task for orders with the anchor and parking type, the following fields are indicated:

Response fragment

{
    "arrival_time_s": 36726.340873455316,
    "node": {
        "type": "location",
        "used_time_window": "12:00:00-18:00:00",
        "value": {
            "anchor_mode": "Decoupling",
            "hard_window": false,
            "id": 1,
            "penalty": {
                "out_of_time": {
                    "fixed": 1000,
                    "minute": 17
                }
            },
            "point": {
                "lat": 55.780426,
                "lon": 37.712129
            },
            "ref": "",
            "service_duration_s": 0,
            "shared_service_duration_s": 0,
            "time_window": "12:00:00-18:00:00",
            "total_service_duration_s": 0,
            "trailer_decoupled": true,
            "trailer_used": true,
            "type": "anchor"
        }
    },
    "transit_distance_m": 4035.227074751774,
    "transit_duration_s": 726.3408734553194,
    "violations": [],
    "waiting_duration_s": 6473.659126544684
}
Copied to clipboard

The following fields are indicated in the solution only for orders with the anchor type:

Response fragment

{
    "route": [
        {
            "arrival_time_s": 49003,
            "departure_time_s": 52603,
            "load_to_head": [
                "Order 1",
                "Order 2",
                "Order 3",
                "Order 4"
            ],
            "node": {
                "type": "location",
                "used_time_window": "08:00:00-14:00:00",
                "value": {
                    "anchor_mode": "Rolling",
                    "hard_window": false,
                    "id": "anchor43",
                    "point": {
                        "lat": 52.527983,
                        "lon": 85.227133
                    },
                    "ref": "",
                    "service_duration_s": 3600,
                    "shared_service_duration_s": 0,
                    "time_window": "08:00:00-14:00:00",
                    "total_service_duration_s": 3600,
                    "trailer_decoupled": true,
                    "trailer_used": true,
                    "type": "anchor"
                }
            }
        }
    ]
}
Copied to clipboard

When performing the routing task with trailers, the following fields are indicated:

Response fragment

{
    "route": [
        {
            "arrival_time_s": 0,
            "departure_time_s": 5040,
            "load_to_head": [
                "Order 5",
                "Order 6",
                "Order 7",
                "Order 8"
            ],
            "load_to_trailer": [
                "Order 1",
                "Order 2",
                "Order 3",
                "Order 4"
            ],
            "node": {
                "type": "depot",
                "used_time_window": "00:00:00-1.23:59:59",
                "value": {
                    "finish_service_duration_s": 1800,
                    "flexible_start_time": true,
                    "hard_window": true,
                    "id": "576",
                },
                "point": {
                    "lat": 53.400374288503,
                    "lon": 83.967696868016
                },
                "preliminary_service_duration_s": 0,
                "ref": "",
                "service_duration_s": 5040,
                "time_window": "00:00:00-1.23:59:59",
                "total_service_duration_s": 5040,
                "trailer_decoupled": false,
                "trailer_used": true
            }
        }
    ]
}
Copied to clipboard

Diagram

Example 1

In the example, one truck with a trailer must deliver three orders. You can arrive at one of the points with a trailer (allow_trailers = true), to the other two — no (allow_trailers = false). There are points near non-accessible locations where you can leave a trailer for some time (type = parking).

In the resulting solution, a truck first drives to the parking point, leaves a trailer there, and then goes to unload the cargo at a non-accessible location. After the cargo is delivered, it returns to the parking lot, picks up the trailer, and continues the route.

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

Example 2

In the example, one truck with a trailer must deliver four orders. You can't arrive at two points with a trailer (allow_trailers = false), but you can at the other two (allow_trailers = true). There is also an anchor location (type = anchor) on the route, where you can leave a trailer for a long period of time.

The algorithm builds a route taking into account non-accessible locations. The truck first arrives at the anchor location and leaves the trailer. It delivers orders to the points where trailers are forbidden. Then it returns to the anchor location to pick up the trailer and delivers the cargo where trailers are allowed.

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

Example 3

In the example, one truck with a trailer must deliver four orders to points where trailers are forbidden (allow_trailers = false). There is an anchor location (type = anchor) on the route. The total weight of orders is much greater than the vehicle capacity. The truck can't deliver all orders without using a trailer.

The truck first arrives at the anchor location, leaves the trailer, and delivers two orders without it. Then it returns to the anchor location, rolls the cargo from the trailer to the tractor, and again leaves without the trailer to deliver the remaining orders.

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

Contact support