Instructions for filling in Excel files

General description

You can download a sample Excel file here. Uploadable formats: xls, xlsx, xlsm.

To upload routing data correctly, the Excel workbook must contain the following sheets:

  • Orders: Information about orders.

  • Vehicles: Information about vehicles or couriers.

  • Depot or Depots: Information about the depot point.

Optionally, the Excel workbook can contain the following sheets:

  • Incompatible_order_types: Information about mutually incompatible order types.

  • Location_groups: Order group settings.

  • Options: Routing options.

  • Routes: Data on predefined routes (routes of logistics coordinators or routes from past planning that need to be preserved in the current planning).

The Excel workbook can also contain sheets with other names and additional information for the user: this won't affect the upload.

To avoid upload errors, don't change the table header on the sheet (the first few rows with the field name and the technical name of the attribute). You can delete optional columns (or add other columns with reserved names), provided that there are no empty columns between the ones filled in.

Note

Columns can be in any order.

Orders sheet

This sheet contains information about orders. Strictly speaking, each row on this sheet is not an order but a location. Therefore:

  • If a simple delivery is made from a depot point, then each row corresponds to an order.

  • If a delivery is made from point A to point B, this order is split into 2 rows: one row corresponds to the pickup point and the other row corresponds to the delivery point.

  • If the start or end point of the route differs from the depot point, this point will be entered in a separate row on the sheet.

Note

For the Orders sheet, you only need to fill in the following minimum set of fields (if you deliver from a depot):

  • Order number

  • Coordinates and/or address of the order.

  • Time window of the order.

  • Volume and weight characteristics of the order (weight and/or volume and/or number of cargo units).

In the other fields, you can leave the default (or empty) values and it will work for the first run of the routing task.

Below, you can see the fields allowed on the Orders sheet.

Basic order information

Excel field group

Attributes

Comments on entering data

Required field

Order number; additional order number

id; ref

We recommend that you specify the order number in id (you can leave ref blank or enter the same data as in id). Learn more

Yes (one of the fields)

Latitude; longitude

point.lat; point.lon

Order location coordinates: latitude (point.lat), longitude (point.lon). Learn more

No, if you specify the order address (when you upload the data via the interface, you can geocode the address)

Client name; brief description of the order point; client address; order comments

title; description; address; comments

Information fields that are displayed in the planning interface later. Learn more

No (but you have to enter the address if the order coordinates aren't entered)

Client phone number

phone

Used only when exporting planning results to Track & Trace.

No

Location type

type

Learn more

Should be filled in for correct routing (technically, the field is optional)

Penalty for non-delivery

penalty.drop

We recommend leaving the default value (1,000,000) or leaving the field empty (in this case, the default value is used). Learn more

Should be filled in for correct routing (technically, this field is optional)

Order characteristics

Excel field group

Attributes

Comments on entering data

Required field

Weight (gross), kg; number of cargo units used; dimensions, m (width, depth, height)

shipment_size.weight_kg; shipment_size.units; shipment_size.volume.width_m; shipment_size.volume.depth_m; shipment_size.volume.height_m

Volume and weight characteristics of the order. Learn more

Should be filled in for correct routing (technically, this field is optional)

Volume, cbm

shipment_size.volume_cbm

Order volume in cubic meters. Learn more

No

Custom units of measurement: name; size

shipment_size.custom.N.name; shipment_size.custom.N.size

Custom units for the order. Learn more

No

Cargo type

shipment_size.volume.type

Possible values: bulk, rigid, fixed_bottom. Learn more

No

Alignment

shipment_size.volume.align

Possible values: all_axes, height. Learn more

No

Delivery windows

Excel field group

Attributes

Comments on entering data

Required field

Time window

time_window

If the time window is relative (meaning that it has the 10:00–18:00 format), the shift of this time window relative to the planning date should be taken into account (the planning date is specified when running the routing task). Learn more here and here

Yes (if time_windows aren't specified)

Multiple time windows

time_windows.N.time_window

We recommend using it if the window has breaks during the day or the windows are different on different days. Can't be used together with time_window. Learn more

Yes (if time_window isn't specified)

Flag of hard time window, TRUE/FALSE

hard_window

TRUE: The shift's time window can't be violated under any circumstances. FALSE: The time window may be violated (if this helps to allocate resources better). You may leave this field empty. In this case, the time window is soft: it may be violated. Learn more Please note: the hard_time_window and hard_window fields are mutually exclusive.

No

Hard time window

hard_time_window

If the main window of depot operation is soft, you can set a hard time window around it. Learn more Please note: the hard_time_window and hard_window fields are mutually exclusive.

No

Penalties: per minute of time window violation; for violation of time window; for early delivery; per minute of early delivery; for late arrival; per minute of late arrival

penalty.out_of_time.minute; penalty.out_of_time.fixed; penalty.early.fixed; penalty. early.minute; penalty.late.fixed; penalty.late.minute

Penalties for violating the order time window. We recommend that you leave the default values (fixed = 1000, minute = 17) or empty values (in this case, the default value is used). Change this field only when it's clear how that would affect routing. You may need to change it in the following use cases: late arrivals are not allowed (but it's possible to arrive before the time window starts), or vice versa; time window violation is acceptable, if it helps to optimize resources. Learn more

Should be filled in for correct routing (technically, this field is optional)

Time limits

Excel field group

Attributes

Comments on entering data

Required field

Time of pickup order delivery to the depot

delivery_deadline

The time before which a pickup order without an explicit delivery location must be delivered to any depot. Learn more

No

Penalties: for violation of the pickup order delivery time to the depot; per minute of violation of the pickup order delivery time to the depot

penalty.delivery_deadline.fixed; penalty.delivery_deadline.minute

Penalties for late delivery of the order to the depot. We recommend that you leave the default values (fixed = 1000, minute = 17) or empty values (in this case, the default value is used). Only edit these fields if it is important for your purpose. Learn more

No

Time when the order is ready at the depot

depot_ready_time

Time when the order is ready for issue at the depot. Learn more

No

Order depot pick up deadline

depot_expiring_time

The time before which the order should be picked up from the depot. Learn more

No

Limitation of the time the order can be in the vehicle

transit_time.limit_s; transit_time.hard_limit_s

A soft and hard limitation of the time the order can stay in the vehicle. Learn more

No

Penalties: for the violation of the time the order can be in the vehicle; per minute of violation of the time the order can be in the vehicle

penalty.transit_time.fixed; penalty.transit_time.minute

Penalty for the violation of the soft limitation of time the order can spend in the vehicle. Learn more

No

Handling time

Excel field group

Attributes

Comments on entering data

Required field

Time for reloading order in a cross-dock, s

crossdock_service_duration_s

Specified for orders delivered via cross docking. Learn more

No

Time spent on loading the order at the depot

depot_duration_s

For the "delivery" orders, this is the time for loading the order at the depot. Learn more

No

Time for parking, s

parking_service_duration_s

Specified if the courier parks the vehicle and then delivers several orders nearby on foot. Learn more

No

Service duration per location, s; service duration per order, s

shared_service_duration_s; service_duration_s

The time that the vehicle or courier spends at the order location (in seconds). Learn more here and here

Should be filled in for correct routing (technically, this field is optional)

Combining and splitting orders

Excel field group

Attributes

Comments on entering data

Required field

Can be merged into multi-order, TRUE/FALSE

can_be_merged

TRUE by default (the order can be merged into a multi-order). Learn more here and here

No

Split order

can_be_split

If FALSE (that is default), the order can only be delivered in its entirety. If TRUE: The order can be delivered in parts. Learn more

No

Maximum number of parts to split into

max_split_parts

The maximum number of parts you can split the order into. Learn more

No

Divider, propotion; divider, kilos; divider, unit; divider, cubic meters

quant; quant.weight_kg; quant.units; quant.volume_cbm

Sets the size of the minimum split part in proportions, kilograms, cargo units, cubic meters. Learn more

No

Fill the entire vehicle

split_parts_must_fill_whole_vehicle

If TRUE, the part that is split from the order should fill the entire vehicle. Default value: FALSE. Learn more

No

Fixed penalty for not delivering part of the order; penalty for not delivering part of the order

penalty.drop.fixed; penalty.drop.scaled

If the order is split into parts, you can set a fixed penalty and a variable penalty that depends on the size (percentage) of the unassigned part of the order. Learn more

Should be filled in for correct routing (technically, this field is optional)

Assigning an order to a depot or other locations

Excel field group

Attributes

Comments on entering data

Required field

Depot inventory availability

depot_id

Depots that the order can be picked from. You can specify multiple depots for one order, separated by commas. Learn more

No

Destination (for orders with the pickup type)

delivery_to

Used only for scenarios with "pickup" orders. This field is only filled out for orders with the "pickup" type. In this field, specify the "id" of the associated order with the "delivery" type. Note: the ID entered in delivery_to should be unique for each "pickup" order. Learn more

No

Delivery to any point (for orders with the pickup type)

delivery_to_any

Used only for scenarios with "pickup" orders. This field is only filled out for orders with the "pickup" type. In this field, specify the id of the associated order with the drop off type. Note: the ID entered in delivery_to_any may be the same for different "pickup" orders.

No

Pick up from any of the specified points

pickup_from_any

Specified only for "delivery" orders. It's used in scenarios when cargo for delivery can be picked up from any number of points. Learn more

No

Mandatory pickup order delivery to the depot in the current route

pickup_must_reach_depot

If this option is enabled, the pickup order should be delivered to the depot in the current route. Learn more

No

Can be delivered through cross docking

crossdock_mode

Accepts one of the following values: allow (default), deny, mandatory. Learn more

No

Can be dropped in a cross-dock, TRUE/FALSE

may_drop_in_crossdock

Can only be set for "pickup" orders. If TRUE (by default), then the order can be dropped in cross docking, and if FALSE, it can only be dropped at a regular depot. Learn more

No

Distribution and compatibility of orders

Excel field group

Attributes

Comments on entering data

Required field

Type of compatibility with other orders

load_types

Parameters of compatibility between the orders. You can specify multiple comma-separated values of "load_types" for an order. load_typescan include any string explaining the required order property in a user-friendly way. The load_types parameter is case-sensitive. If you enter load_types, fill out the incompatible order types on the sheet Incompatible_order_types. You can't assign incompatible order types when you plan a single run for a single vehicle or courier. Learn more

No

Optional vehicle requirements: tag name; tag weight

optional_tags.N.tag; optional_tags.N.value

Tags for optional requirements. Learn more

No

Vehicle requirements

required_tags

Order and vehicle compatibility parameters. You can specify multiple comma-separated tags for one order. A tag is any string that identifies the necessary properties of the vehicle or courier clearly for the user. Only the vehicle that has all the tags specified for the order can be selected for such an order. Tags are case-sensitive. Learn more

No

Other order characteristics

Excel field group

Attributes

Comments on entering data

Required field

Location availability for vehicle with trailer

allow_trailers

FALSE by default. Learn more

No

Order of reception and delivery

in_lifo_order

FALSE by default. You can use it for pickup/delivery order pairs when the sequence of loading and unloading is important. Learn more

No

Order priority

sequence_order

The sequence of completing orders on a route. Learn more

No

IDs of companies allowed to monitor the order

shared_with_company_ids

Company IDs are separated with commas.Learn more

No

Proximity algorithms allowed, TRUE/FALSE

use_in_proximity

You can disable route proximity options for the order. TRUE by default (proximity options are enabled). Learn more

No

Vehicles sheet

This sheet contains information about available resources (vehicles or couriers). You don't need to enter specific vehicles or names. You can enter abstract resources and assign specific vehicles or couriers to the resulting routes separately and outside of the routing service.

Make sure that you correctly specified all the resources that are available at the time of planning:

  • If these are your own vehicles or couriers, list them taking into account planned unavailability for routes or shifts.

  • If these are hired vehicles or couriers and you don't know how many of them there are in advance, specify how many are usually involved for the given amount of orders. If the types vary, specify the maximum number of involved vehicles for each type. For example, you use hired vehicles with a 1.5-ton and 3-ton capacity, and each time you may use up to 10 vehicles but don't know the number of vehicles of each type in advance. In this case, you can enter 10 identical rows for 1.5-ton vehicles and 10 identical rows for 3-ton vehicles.

Note

In the Vehicles sheet, fill out the following minimum of fields:

  • Number of the vehicle or courier.

  • Capacity of the vehicle or courier.

  • Working hours.

In the other fields, you can leave the default (or empty) values and it will work for the first run of the routing task.

Below, you can see the fields allowed on the Vehicles sheet.

Basic information about the courier or vehicle

Excel field group

Attributes

Comments on entering data

Required field

Courier ID; courier name or number

id; ref

We recommend that you specify the vehicle or courier number in ref (you can leave id blank). The id value must be unique for the entire sheet (ref may be non-unique). If the id field is empty, then when you upload the data from Excel and send the task for routing, the field is set to 0, 1, 2… The id field is also important for exporting the planning results to Track & Trace. It's used as the courier's username in the mobile app. Learn more

Yes (one of the fields)

GPS tracker number

imei

The number of the vehicle's GPS tracker. Used only when exporting the planning results in Track & Trace. Learn more

No

Maximum number of runs

max_runs

The maximum number of runs for all the specified shifts. By default, 1. In the algorithm, a run is a departure from the depot and delivery of orders before returning to the depot (in this case, if the vehicle returns to a point with the coordinates of the depot, that's not counted as a run). Learn more

No

Courier's phone number

phone

The phone number for contacting the courier in Track & Trace. Learn more

No

Transportation method

routing_mode

Filled out only if the vehicles or couriers use different methods of travel (for example, a car and public transit). If the transportation method is the same for everyone, you don't need to fill out this field. When you start a routing task, you can select the method of travel to be used by everyone. Learn more

No

Courier or vehicle characteristics

Excel field group

Attributes**

Comments on entering data**

Required field

Load capacity, kg; maximum load, weight %; number of available cargo units; maximum load, % of cargo units; size of cargo space for a cargo unit, m (Width, Depth, Height); maximum load, % of capacity

capacity.weight_kg; capacity.limits.weight_perc; capacity.units; capacity.limits.units_perc; capacity.volume.width_m; capacity.volume.depth_m; capacity.volume.height_m; capacity.volume_cbm; capacity.limits.volume_perc

Vehicle or courier capacity parameters. capacity.weight_kg: Load capacity in kg. capacity.units: Load capacity in cargo units. capacity.volume_cbm: Vehicle capacity in cubic meters. Besides the nominal carrying capacity, we recommend that you use the limits parameters to specify possible overloads or planned underloads of the vehicles (especially if you use those values to build routes manually or in other programs). Learn more

Should be filled in for correct routing (technically, this field is optional)

Custom capacity units: name; number of units

capacity.custom.N.name; capacity.custom.N.size

Vehicle capacity in custom units. Learn more

No

Vehicle specifications: width, height, length, max weight in tons, max weight in kg

specs.width; specs.height; specs.length; specs.max_weight; specs.max_weight_kg

You can use vehicle specifications to determine whether a vehicle can travel on roads with restrictions. Learn more

No

Minimum order weight for a vehicle

min_stop_weight

The minimum total weight that a vehicle can deliver to one location. Learn more

No

Penalty for violating the minimum total weight; penalty for each kg of total weight less than minimum

penalty.min_stop_weight.fixed; penalty.min_stop_weight.kg

The minimum order weight for a vehicle is a soft restriction. The algorithm takes into account the penalty for violating the minimum total weight of all orders at one location (1000 by default) and the penalty for each missing kilogram in the total weight of orders delivered to one location (50 by default). Learn more

No

Assigning to a depot

Excel field group

Attributes

Comments on entering data

Required field

Allowed to visit multiple depots in one route

allow_different_depots_in_route

FALSE is the default value. The courier can only visit the depot where the route starts. If TRUE, the courier can visit multiple depots on the same route. Learn more

No

Allowed to visit cross-docks

crossdock_mode

Accepts one of the following values: allow (default), deny, mandatory. Learn more

No

Depots that the courier can visit

depot_id

You can specify multiple depots for one courier, separated by commas. Learn more

No

Start point of route; visit depot after route start, TRUE/FALSE

start_at; visit_depot_at_start

Parameters of the starting point for vehicles or couriers before the route start. By default, everyone starts from the depot location. You can specify a different starting point and indicate the requirement to return to the depot after departure from the starting location. Learn more

No

Can visit the depot at the beginning of the route, TRUE/FALSE

can_visit_depot_at_start

FALSE by default. Works only when visit_depot_at_start = false. The courier can visit the depot at the beginning of the route, if necessary. Learn more

No

Return to depot at the end of the shift, TRUE/FALSE; end point of route

return_to_depot; finish_at

Parameters for the return of a vehicle or courier after the route is completed (1. To the depot. 2. To an arbitrary point. 3. First to the depot, then to an arbitrary point). By default, return_to_depot = true (it means that the vehicle returns to the depot). If you leave the field empty, the default value is used. Learn more

No

Depots to start from

starting_depot_id

Depots that the courier can start from. You can specify multiple depots for one courier, separated by commas. Learn more

No

Depots for additional loading

middle_depot_id

Depots that a courier can visit while on the route to additionally load "delivery" orders or unload "pickup" orders. You can specify multiple depots for one courier, separated by commas. Learn more

No

Maximum number of depots for additional loading in one route

max_middle_depots

The maximum number of intermediate depots that a courier can visit while on the route. Learn more

No

Depots to end the route at

ending_depot_id

Depots where the courier can end the route. You can specify multiple depots for one courier, separated by commas. Learn more

No

Time limits

Excel field group

Attributes

Comments on entering data

Required field

Loading time, depending on the vehicle, s

depot_extra_service_duration_s

The time needed for loading in addition to the depot's general handling time. Learn more

No

Time of the first order visited

first_visited_location_started_at

Optionally, you can specify the start time for the first order in the first_visited_location_started_at field. Use it in case of additional planning and when you want to lock part of the route (or the whole route) in a particular sequence.

No

Deliver as soon as possible: need to start early; penalty for the average time of arrival after the time window

penalty.arrival_after_start.as_soon_as_possible; penalty.arrival_after_start.average_h

The fields are used together and specify the need to deliver all orders as soon as possible. Learn more

No

Distribution by zone and compatibility

Excel field group

Attributes

Comments on entering data

Required field

Vehicle properties; incompatible vehicle properties

tags; excluded_tags

Parameters for order and vehicle compatibility. For a single vehicle, you can specify multiple tags, the tags are separated by commas. A tag is any string that identifies the necessary properties of the vehicle or courier clearly for the user. Only the vehicle having all the tags specified for the order can be selected for the order. Tags are case-sensitive. Use excluded_tags when you have too many vehicles or tags and it's easier to use the "opt-out" method (that is, to specify the properties that the vehicles don't have). Learn more

No

Allowed geofences

allowed_zones

Geofences where the vehicle or courier can deliver orders. Learn more

No

Prohibited geofences

forbidden_zones

Geofences where the vehicle or courier can't deliver orders. Learn more

No

Optional geofences

optional_zones.N.zone; optional_zones.N.value

Geofences that carry bonuses or penalties for vehicles or couriers. Learn more

No

Incompatible geofences

incompatible_zones

Geofences that can't be in the same courier run. Learn more

No

Cost and payouts

Excel field group

Attributes

Comments on entering data

Required field

Cost of using a vehicle: per km; per location; per hour of work; for the fact of using a vehicle; per ton-kilometre; per run

cost.km; cost.location; cost.hour; cost.fixed; cost.tonne_km; cost.run

The cost of using the vehicle or courier for the algorithm (not a rate, but a reference point for the algorithm to select a particular routing option). The cost.km and cost.hour must not be equal to 0. If you don't know what to enter in those fields, we recommend leaving the default value (cost.fixed = 3000, cost.hour = 100, cost.km = 8) or leaving them empty (in this case, the default values apply). Learn more

Yes

Formula for calculating the cost of using a vehicle

cost or cost.route, cost.shift, cost.run

A mathematical expression for calculating the cost of a route for the company. It is set for the route as a whole or separately for the route, shift, and run. Learn more

No

Formula for calculating the courier's payout

payout or payout.route, payout.shift, payout.run

A mathematical expression for calculating the amount to be paid to the courier for the completed route. It is set for the route as a whole or separately for the route, shift, and run. Learn more

No

Restrictions for walking couriers or parts of the route

Excel field group

Attributes

Comments on entering data

Required field

Maximum number of units that the walking courier can carry

walking_courier.capacity.units

Used in delivery scenarios where a courier parks their vehicle before the walking part of the route. Learn more

No

Cost of walking delivery

walking_courier.cost.km; walking_courier.cost.hour

Used in delivery scenarios where a courier parks their vehicle before the walking part of the route. Learn more

No

Maximum distance between two points of walking parts of the route, m; penalty for violating the restriction

walking_courier.restrictions.max_walking_edge_distance_m.value; walking_courier.restrictions.max_walking_edge_distance_m.penalty

Used in delivery scenarios where a courier parks their vehicle before the walking part of the route. Learn more

No

Maximum walking distance in a parking session, m; penalty for violating the restriction

walking_courier.restrictions.max_parking_walking_distance_m.value; walking_courier.restrictions.max_parking_walking_distance_m.penalty

Used in delivery scenarios where a courier parks their vehicle before the walking part of the route. Learn more

No

Maximum duration of a parking session, s; penalty for violating the restriction

walking_courier.restrictions.max_parking_duration_s.value; walking_courier.restrictions.max_parking_duration_s.penalty

Used in delivery scenarios where a courier parks their vehicle before the walking part of the route. Learn more

No

Trailers

Excel field group

Attributes

Comments on entering data

Required field

Trailer capacity, kg

trailer.capacity.weight_kg

Trailer capacity in kilograms. Learn more

No

Trailer capacity, units

trailer.capacity.units

Trailer capacity in units. Learn more

No

Maximum difference between trailer and truck load, units

trailer.max_capacity_difference.units

How many more units there can be in the trailer than in the truck. Learn more

No

Maximum difference between trailer and truck load, kg

trailer.max_capacity_difference.weight_kg

By how many kilograms the trailer load can exceed the truck load. Learn more

No

Trailer cost, fixed

trailer.cost.fixed

Fixed trailer cost. Learn more

No

Trailer decoupling time, sec

trailer.decoupling_time_s

Trailer decoupling time in seconds. Learn more

No

Trailer coupling time, sec

trailer.coupling_time_s

Trailer coupling time in seconds. Learn more

No

Rolling time, sec

trailer.rolling_time.fixed_time_s

Fixed time for rolling the cargo from trailer to truck in seconds. Learn more

No

Other characteristics of couriers and vehicles

Excel field group

Attributes

Comments on entering data

Required field

Need to leave the planned route unchanged

fixed_planned_route

The need to leave the route from planned_route unchanged. Default value: FALSE. Learn more

No

Service time coefficient

service_duration_multiplier; shared_service_duration_multiplier

The coefficient of acceleration or deceleration of vehicles or couriers relative to the service time. We only recommend this option for more experienced users. Learn more

No

Speed coefficient

travel_time_multiplier

The coefficient of acceleration or deceleration of vehicle or courier relative to the speed calculated from statistics. We only recommend this option for more experienced users. Learn more

No

Shifts

You can specify multiple shifts for one vehicle or courier. Enter the values in one row as follows: first, the field group with the shifts.0 prefix, then shifts.1, shifts.2, and so on. This number serves as the shift identifier for the route planning service.

Note

At least one shift must be defined.

Excel field group

Attributes

Comments on entering data

Required field

Start and end time of the shift; hard time window of the shift

shifts.N.time_window; shifts.N.hard_time_window

Time when drivers are available for route planning. If the regular working hours for vehicles/couriers are, for example, 9:00 to 17:00 (with some overtime on occasion), it's better to specify the available working hours right away, for example, 9:00 to 17:30). When setting the time window for the shift, it's critical to account for the time at the beginning of the route and the time at the end of the route, because the algorithm considers these times to be included in the vehicle or courier's working hours. If the vehicle or courier returns to the depot, this time is also taken into account in the vehicle or courier working hours (and should be reflected in the shift's time window). Learn more. Please note: the hard_time_window and hard_window fields are mutually exclusive.

Yes

Hard time window, TRUE/FALSE

shifts.N.hard_window

TRUE: The shift's time window can't be violated under any circumstances. FALSE: The shift's time window can be violated (if this helps to allocate resources better). You may leave this field empty. In this case, the time window is soft: it may be violated. Learn more. Please note: the hard_time_window and hard_window fields are mutually exclusive.

No

Maximum number of runs per shift

shifts.N.max_runs

The maximum number of runs that can be performed per shift. Learn more

No

Time between shifts, s

shifts.N.service_duration_s

We recommend specifying this time only when a vehicle has several consecutive shifts, even with overlapping time windows. For example, Shift 1: 9:00 to 14:00, Shift 2: 13:00 to 18:00. It means that Shift 1 may end before 14:00, but never later than that. Likewise, Shift 2 may not begin before 13:00, but may begin later. If you need to use both shifts for routing, this parameter is added between those two shifts. Learn more

No

Penalties: per minute of shift window violation; for the violation of the shift window; per minute of early shift start; for early shift start; per minute of late shift end; for late shift end

shifts.N.penalty.out_of_time.minute; shifts.N.penalty.out_of_time.fixed; shifts.N.penalty.early.minute; shifts.N.penalty.early.fixed; shifts.N.penalty.late.minute; shifts.N.penalty.late.fixed

Penalties for violating the order time window. We recommend that you leave the default values (fixed = 1000, minute = 17) or empty values (in this case, the default value is used). Change this field only when it's clear how that would affect routing. Changes may be needed in the following scenarios: early start of the shift is not allowed (but late end of the shift is possible), or vice versa. Violation of the shift time window is acceptable if this results in better use of resources. A hard shift window and the Maximum shift duration. Learn more

No

Maximum shift duration, s: soft restriction; hard restriction

shifts.N.max_duration_s; shifts.N.hard_max_duration_s

We recommend leaving it blank when you first start routing. Learn more

No

Maximum shift duration, s: soft restriction; hard restriction

shifts.N.max_working_duration_s; shifts.N.hard_max_working_duration_s; shifts.N.penalty.working_overtime.fixed; shifts.N.penalty.working_overtime.minute

We recommend leaving it blank when you first start routing. Learn more

No

Minimum number of stops per shift; penalty per each stop missing under the minimum number; penalty for not reaching the minimum number of stops

shifts.N.minimal_stops; shifts.N.penalty.stop_lack.per_stop; shifts.N.penalty.stop_lack.fixed

We recommend leaving it blank when you first start routing. You can make it mandatory for your own vehicles later. Learn more

No

Maximum number of stops per shift; penalty per each stop in excess of the maximum number; penalty for exceeding the maximum number of stops

shifts.N.maximal_stops; shifts.N.penalty.stop_excess.per_stop; shifts.N.penalty.stop_excess.fixed

We recommend leaving it blank when you first start routing. You can later use it to limit the number of points on the route: for heavy vehicles (if you can't limit it by other parameters, for example, by service time ). You can also use it to set empirical limits on the number of points on the route (for example, if it's proven that the courier can't complete a route of more than a certain number of points without violations because of contingencies). Learn more

No

Maximum mileage per shift, km; penalty for the fact that mileage exceeds maximum; penalty for each km of mileage in excess of maximum

shifts.N.max_mileage_km, shifts.N.penalty.max_mileage.fixed; shifts.N.penalty.max_mileage.km

We recommend leaving it blank when you first start routing. You can use it to limit the mileage of vehicles or couriers per shift later. Learn more

No

Balanced group ID

shifts.N.balanced_group_id

We recommend leaving it blank when you first start routing. If you need to get more uniform distribution of orders across vehicles or couriers, you can fill out the balanced groups on the Options sheet and specify the balanced group ID in this field.Learn more

Нет

Visited orders; time of the first order visited

shifts.N.visited_locations

You can list the id of the orders that have already been assigned to this vehicle in the shifts.N.visited_locations field. The sequence is critical in this list.

No

Breaks

You can specify multiple breaks for one vehicle or courier. Enter the values in one row as follows: first, the field group with the rest_schedule.breaks.0 prefix, then rest_schedule.breaks.1, rest_schedule.breaks.2, and so on.

Excel field group

Attributes

Comments on entering data

Required field

Duration of the break, s

rest_schedule.breaks.N.rest_duration_s

Duration of the break in seconds. Learn more

No

Penalties: for an early break start; per minute of an early break start; for a late break start; per minute of a late break start

rest_schedule.breaks.N.penalty.early.fixed; rest_schedule.breaks.N.penalty.early.minute; rest_schedule.breaks.N.penalty.late.fixed; rest_schedule.breaks.N.penalty.late.minute

Break is a soft restriction: in some cases, it may start earlier or later than the range defined in the work_time_range_till_rest field. The algorithm takes penalties into account: early, if a break started before the range; late, if the break started later than the range. The higher are the penalties, the more severe is the restriction violation. We recommend that you use the default values (fixed = 1000, minute = 17) or empty values (then the default values are used). Learn more

No

Working hours from the start of the route

rest_schedule.breaks.N.work_time_range_from_start

Minimum and maximum working hours from the start of the route. It takes into account the travel time, waiting time, and handling time at order locations and at the depots. Set as a time range in the relative format. Learn more

No

Working hours from the last break

rest_schedule.breaks.N.work_time_range_till_rest

The minimum and maximum working hours from the last break (or from the start of the route, if it's the first break). It takes into account the travel time, waiting time, and handling time at order locations and at the depots. Set as a time range in the relative format. Learn more

No

Driving time and waiting time from the start of the route

rest_schedule.breaks.N.travel_time_range

The minimum and maximum travel time and waiting time from the start of the route. Handling time is not taken into account. Set as a time range in the relative format. Learn more

No

Driving time and waiting time from the previous order

rest_schedule.breaks.N.continuous_travel_time_range

The minimum and maximum travel time and waiting time from the completion of the previous order. Handling time is not taken into account. Set as a time range in the relative format. Learn more

No

rest_schedule.breaks.N.at_rest_place

Determines if a courier can take a rest at a location with the rest_place type. Learn more

No

Depot or Depots sheet

The Depot sheet contains information about the depot that the shipment is going to be made from. Only one row is filled out on this sheet.

If you use multiple depots, you need the Depots sheet, where any number of depots can be specified.

You have to fill out at least one depot row. If the vehicles or couriers don't start from the depot and don't return to the depot at the end of the route (there's no location that they could be assigned to), you can specify the coordinates of any point as a depot, for example, the coordinates of the office or city center.

Depot and Depots sheets are mutually exclusive, so you can use only one of them.

Note

On the Depot/Depots sheet, you only have to fill out the following fields:

  • Depot name (you can just enter "Depot").

  • Depot coordinates or address.

  • Depot working hours (you can set the maximum time window: 00:00–23:59 for the current planning day or 00:00–1.23:59 for the current and next planning days).

In the other fields, you can leave the default (or empty) values and it will work for the first run of the routing task.

The table below describes the acceptable fields on the Depot/Depots sheet.

Basic depot information

Excel field group

Attributes

Comments on entering data

Required field

Depot number

id

The depot id shouldn't match any order id.`` If the id field is empty, then when you upload the data from Excel and send the task for routing, the field is populated by 0. Learn more

Yes

Depot name; depot title; depot description

ref; title; description

The depot's numeric or string ID to be displayed in the Planning interface; depot name; depot description. Learn more

No

Latitude; longitude

point.lat; point.lon

Depot location coordinates: latitude (point.lat), longitude (point.lon). Learn more

No, if you specify the depot address (when you upload data from the interface, you can geocode the address)

Depot address

address

Address for geocoding. Learn more

No (but if the depot coordinates aren't entered, you must enter the address)

Depot time windows

Excel field group

Attributes

Comments on entering data

Required field

Depot working hours

time_window

If you don't have any special requirements for the time when vehicles should return to the depot or for depot throughput capacity, we recommend that you specify the broadest possible working hours for the depot. For example: 00:00–23:59 for single-day planning or 00:00–1.23:59 for 2-day planning. Learn more

Yes (if time_windows aren't specified)

Multiple time windows

time_windows.N.time_window

We recommend using it if the window has "breaks" during the day or the windows are different on different days. Can't be used together with time_window. Learn more

Yes (if time_window isn't specified)

Hard time window interval

hard_time_window

If the main window of depot operation is soft, you can set a hard time window around it. Learn more. Please note: the hard_time_window and hard_window fields are mutually exclusive.

No

Hard time window, TRUE/FALSE

hard_window

TRUE: The depot's time window can't be violated under any circumstances. FALSE: The depot's time window may be violated (if this helps to allocate resources better). You may leave this field empty. In this case, the time window is soft: it may be violated. Learn more. Please note: the hard_time_window and hard_window fields are mutually exclusive.

No

Time windows (soft and hard) for loading, additional loading, or unloading orders at the depot

time_windows_loading.time_window; time_windows_loading.hard_time_window; time_windows_refilling.time_window; time_windows_refilling.hard_time_window; time_windows_unloading.time_window; time_windows_unloading.hard_time_window

You can set one window or an array of windows for each window type. If a window of some type is not set, the general depot time window is used for the corresponding operation. Learn more

No

Time before the start of each run until the order is ready at the depot, s

preliminary_service_duration_s

Specify if you need to perform preliminary operations at the depot before the order is ready. Learn more

No

Penalties for time window violations: per minute of violation of depot's time window; for the violation of depot's time window; for the violation of the depot's time window (early arrival); per minute of violation of the depot's time window (early arrival); for the violation of the depot's time window (late arrival); per minute of violation of the depot's time window (late arrival)

penalty.out_of_time.minute; penalty.out_of_time.fixed; penalty.early.fixed; penalty.early.minute; penalty.late.fixed; penalty.late.minute

Penalties for order time window violations. Leave the default values (fixed = 1000, minute = 17) or empty values (in this case, the default value is used). Only edit these fields if it is important for your purpose. Learn more

No

Handling time at depot

Excel field group

Attributes

Comments on entering data

Required field

Handling time at the start of the run, s; handling time at the end of the run, s

service_duration_s; finish_service_duration_s

When filling it out, take into account the time window of the shift. For example, if you only need to fill out the time that should only be added between the runs, you can do the following: 1. Use only service_duration_s. 2. Bring forward the start of the first shift by service_duration_s. For example, drivers work from 9:00 to 17:00. You need to allow 30 minutes for loading between runs. At the start of the route, the vehicles are already loaded. If the drivers depart at 9:00, schedule a shift from 8:30 to 17:00 and set service_duration_s to 1800 (the algorithm will assume that the working hours begin at 8:30, half an hour is allowed for loading, and departure is possible at 9:00. In the future, this half-hour will be added between runs). Learn more

No

Time interval from unloading order at cross-dock till loading for next route, s

crossdock_safety_waiting_duration_s

Time buffer for cross docking: the minimum amount of time that should pass after unloading the order at the cross docking and before this order can be picked up for delivery to the client. Learn more

No

Depot throughput capacity

Excel field group

Attributes

Comments on entering data

Required field

Throughput, kg/hour; throughput, cargo units/hour

throughput.kg_per_hour; throughput.units_per_hour

We recommend leaving these fields blank for your first routing runs. Before using the throughput parameters, we recommend using flexible_start_time. In practice, it has the same effect as distributing the vehicle start time over time. Learn more

No

Throughput, vehicles/hour

throughput.vehicle_count or throughput.vehicle_count.N.value; throughput.vehicle_count.N.time_window

You can use it to take into account the number of docks available for loading or unloading (throughput.vehicle_count). If the number of available docks depends on the time, you can set a different value for the throughput.vehicle_count.N.value parameter for throughput.vehicle_count.N.time_window time windows. Learn more

No

Penalties for the throughput violation: fixed penalty; per kilogram of excess throughput; for each cargo unit in excess of throughput; for each vehicle in excess of throughput

penalty.throughput.fixed; penalty.throughput.kg; penalty.throughput.unit; penalty.throughput.vehicle

We recommend leaving these fields blank for your first routing runs. Next, you can use the default values (penalty.throughput.fixed = 1000, penalty.throughput.kg = 50, penalty.throughput.unit = 100, penalty.throughput.vehicle = 100000) and adjust them based on the results. Learn more

No

Staging throughput capacity, kg/hour

package_throughput.kg_per_hour or package_throughput.kg_per_hour.N.value; package_throughput.kg_per_hour.N.time_window

Sets the maximum weight that can be staged at the depot in one hour. If the maximum weight depends on the time, you can set different values for time windows. Learn more

No

Staging throughput capacity, cargo units/hour

package_throughput.unit_per_hour or package_throughput.unit_per_hour.N.value; package_throughput.unit_per_hour.N.time_window

Sets the maximum number of cargo units that can be staged at the depot in one hour. You can set different values for time windows. Learn more

No

Fixed penalty for staging throughput capacity violation; penalty per kilogram over staging throughput capacity; penalty for every cargo unit over the staging throughput capacity

penalty.package_throughput.fixed; penalty.package_throughput.kg; penalty.package_throughput.unit

We recommend leaving these fields blank for your first routing runs. Next, you can use the default values (penalty.package_throughput.fixed = 1000, penalty.package_throughput.kg = 50, penalty.package_throughput.unit = 100) and adjust them based on the results.

No

Other depot settings

Excel field group

Attributes

Comments on entering data

Required field

Flexible start time, TRUE/FALSE

flexible_start_time

Use this parameter to get the required start time for the vehicle or courier. If the courier's working hours are counted from the shift start, you don't need to enable this parameter. Learn more

No

Proximity algorithms allowed, TRUE/FALSE

use_in_proximity

Whether or not depot proximity is taken into account when building grouped routes. Learn more

No

Incompatible_order_types sheet

This sheet contains settings for incompatible order types. If you don't use order incompatibility (load_types field), you can leave this sheet blank.

There are only 2 columns on this sheet: in the type column, specify one load_types value. In the incompatible_load_types column, list incompatible load_types separated by commas. You only need to specify each pair of incompatible "load_types" once.

For example, if types 1, 2, 3, and 4 are incompatible, the following rows are enough:

type

incompatible_load_types

1

2,3,4

2

3,4

3

4

Location_groups sheet

This sheet contains settings for order groups. If you don't use order groups (the options.location_groups field), you may leave this sheet blank.

Excel field group

Attributes

Comments on entering data

Required field

Name of order group

title

Group name. Doesn't affect planning, you can use it to improve the convenience of working with multiple groups

No

IDs of orders

location_ids

A list of order id in the group. Separated by commas. One order can belong to 1 group only

Yes

Group can't be broken up

solid

FALSE by default. The TRUE value specifies that the group can't be broken up: orders in it must be delivered without other orders between them. Order sequence within the group isn't fixed. Learn more

No

Group is indivisible

dependent

FALSE by default. The TRUE value specifies that the group can't be divided: all orders in it should either be completed or (if at least one order can't be delivered) set to unassigned together.Learn more

No

Options sheet

This sheet contains routing options. Options are entered in one row. For the first run of the routing, you may leave the values in this sheet blank.

The table below describes the acceptable fields on the Options sheet.

For late arrivals and unassigned orders

Excel field group

Attributes

Comments on entering data

Required field

Maximum share of unassigned orders

max_drop_penalty_percentage

100 by default. Learn more

No

Fixed penalty for violation of maximum share of unassigned orders; penalty for each extra percentage of the ratio of the total penalty for unassigned orders to the maximum possible

penalty.drop_penalty_percentage.fixed; penalty.drop_penalty_percentage.per_percent

Penalties are only imposed when you use the max_drop_penalty_percentage parameter. Learn more

No

Penalty for non-delivery is proportional to the weight/volume of orders

weighted_drop_penalty

FALSE by default. We recommend using TRUE in scenarios where orders have significantly different weight or volume and you use vehicles of different capacities (and the number of vehicles is such that you should use them often to deliver all the orders).

No

Penalize for a service that's later than the time window

penalize_late_service

FALSE by default. We recommend using the TRUE value to increase matches between service time and order windows. Learn more

No

For multi-orders

Excel field group

Attributes

Comments on entering data

Required field

Combine orders into multi-orders?

merge_multiorders

We recommend setting it to TRUE: most of the time, that's the expected use case. Learn more

No

Merge service time for multiorders

wait_in_multiorders

If FALSE, the client_service_duration_s time is accounted separately for each order in a multi-order. If TRUE, the maximum value of the client_service_duration_s parameter is taken into account from all orders in the multi-order. Default value: TRUE. Learn more

No

Penalty for each multi-order address that had to be visited again; for each repeated arrival at the multi-order address; for each courier that visits the multi-order address again

penalty.multiorders.per_extra_point; penalty.multiorders.per_extra_visit; penalty.multiorders.per_extra_vehicle

Penalties for return visits to multi-order points. Learn more

No

For split orders

Excel field group

Attributes

Comments on entering data

Required field

Maximum share of split orders, %

max_split_orders_percentage

This determines the maximum percentage of orders that can be split. The value can range from 0 to 100 (100 by default). Learn more

No

Penalties: for deviation from the maximum share of split orders; for each excess percent of splitting

penalty.split_orders_percentage.fixed; penalty.split_orders_percentage.per_percent

Penalties are only imposed when you use the max_split_orders_percentage parameter. Learn more

No

For depots

Excel field group

Attributes

Comments on entering data

Required field

Loading when ready

load_when_ready

Defines the scenario of loading orders at the depot. FALSE by default, loading after all orders are ready. If the courier should start loading orders as they are get ready, specify the TRUE value, the time when ready location.depot_ready_time, and the loading time location.depot_duration_s. Learn more

No

Penalty for each unused starting, middle and ending depot

penalty.unused_depot.starting, penalty.unused_depot.middle, penalty.unused_depot.ending

Penalty for each visited depot with no loaded or unloaded orders.

No

For other locations

Excel field group

Attributes

Comments on entering data

Required field

Coordinates of the location that throughput is set for

points_throughputs.N.point.lat; points_throughputs.N.point.lon

We recommend leaving it blank when you first start routing. Learn more

No

Location throughput: kg per hour; unit per hour; vehicle per hour

points_throughputs.N.throughput.kg_per_hour; points_throughputs.N.throughput.unit_per_hour; points_throughputs.N.throughput.vehicle_count

We recommend leaving it blank when you first start routing. Learn more

No

Penalties for violation of location throughput capacity: fixed; for each kilogram in excess of location throughput capacity; for each cargo unit in excess of location throughput capacity; for each vehicle simultaneously loaded or unloaded at the location over the throughput capacity

points_throughputs.N.penalty.throughput.fixed; points_throughputs.N.penalty.throughput.kg; points_throughputs.N.penalty.throughput.unit; points_throughputs.N.penalty.throughput.vehicle

We recommend leaving it blank when you first start routing. As you gain more experience, try using the default values (penalty.throughput.fixed = 1000, penalty.throughput.kg = 50, penalty.throughput.unit = 100, penalty.throughput.vehicle = 100000) and adjust them based on the results.

No

For couriers and vehicles

Excel field group

Attributes

Comments on entering data

Required field

Excluded zones

avoid_zones

Geofences that are off-limits to all couriers. Learn more

No

Enable vehicle classes for trucks

enable_vehicle_classes

If enabled, class 21 specifications are used to calculate the truck capacity. Default value: TRUE. Learn more

No

Fix planned shifts

fix_planned_shifts

You can use it to fix the courier shifts that are set in planned_route. Default value: FALSE. Learn more

No

Allocation of problem orders

haversine_fallback

With this option enabled, orders in an excluded zone are planned, but the route segment length is calculated as five times the direct distance. Default value: FALSE. Learn more

No

Counting the minimum number of stops for active couriers only

ignore_min_stops_for_unused

Enable this option to optimize the number of vehicles on the route when a minimum number of stops is required. Default value: FALSE. Learn more

No

Incompatible geofences

incompatible_zones.N

Geofences that the vehicle or courier can't visit on the same run.Learn more

No

Transportation method for all couriers

routing_mode

Use it only if all vehicles or couriers use the same transportation method. If there are different transportation methods, the respective parameter is set separately for each vehicle. Learn more

No

For routes

Excel field group

Attributes

Comments on entering data

Required field

Group ID; penalty for deviation from the average time; penalty for deviation from the average stops (orders); penalty for deviating from the average route for custom_value; penalty per kilometer of deviation from the average route length; penalty for deviation from the average number of orders; penalty for deviation from the average number of units on the route; penalty (in kg) for deviation from the average route mass; ignore unused vehicles for penalty calculations

balanced_groups.N.penalty.hour; balanced_groups.N.penalty.stop; balanced_groups.N.penalty.custom_value; balanced_groups.N.penalty.km; balanced_groups.N.penalty.served_order; balanced_groups.N.penalty.unit; balanced_groups.N.penalty.weight_kg; balanced_groups.N.penalty.ignore_unused_vehicles

We recommend leaving the default values and not using these for initial routing runs. If you need routes with a more even distribution, you can fill out the balanced groups using the default values at first. Then you can gradually change the settings based on the results. You can specify multiple balanced groups. Enter the values in one row as follows: first, the field group with the balanced_groups.0 prefix, then balanced_groups.1, balanced_groups.2, and so on. Learn more

No

Minimizing risk of late arrivals

minimize_lateness_risk

We recommend leaving it as FALSE (default value) and not using it for initial routing runs. Learn more

No

Global route density factor

global_proximity_factor

We recommend leaving it as 0 (default value) and not using it for initial routing runs. Value range: 0 to 10. The higher the value, the higher the density of routes. Learn more

No

Order location proximity factor

proximity_factor

We recommend leaving it as 0 (default value) and not using it for initial routing runs. If you need to achieve higher grouping on your routes, you can gradually increase this value by a small step (for example, 0.1). If the geography of locations is naturally spread out (for example, a city and its suburbs), we don't recommend using values more than 0.5. Learn more

No

Other options

Excel field group

Attributes

Comments on entering data

Required field

Matrix router

matrix_router

Defines the algorithm used for planning routes. Default value: main in Russia, Turkey, and CIS countries. For other countries, the value is global. To calculate the distance directly, without taking traffic into account, use geodesic.

No

Sequence post-optimization

post_optimization

Default value: FALSE. We recommend enabling TRUE in scenarios where balancing with high penalties or a geographic grouping with high global_proximity_factor is used. Learn more

No

Restart optimization job

restart_on_drop

Restart the planning task if many orders remain unassigned. Default value: FALSE. Learn more

No

Routes sheet

Fill this sheet out in the following situations:

  • When you need to use the results of previous planning in current planning (see Additional route planning). This sheet repeats the situation with additional planning, when the vehicles haven't left the depot yet.

  • When you need to simulate a ready-made planning, such as a logistics coordinator planning, or calculate the metrics for the planning. Note that by default, the algorithm will optimize the order sequence specified for this vehicle ID.

If you need to take the order sequence into account, use the vehicle.fixed_planned_route = true option (see the section Planned route). Then the order of the rows will be important: for this vehicle ID, it will be assumed that orders are delivered in the same sequence as they are listed: from top to bottom.

Excel field group

Attributes

Comments on entering data

Required field

Vehicle ID

vehicle_id

ID of the vehicle or courier for which the set of assigned orders is defined.

Yes (if the Routes sheet is used)

Shift number

shift_index

The number of the shift that is used in the Excel template (0, 1, 2…)

Yes (if the Routes sheet is used)

Location ID

location_id

ID of the order that was assigned to this vehicle or courier.

Yes (if the Routes sheet is used)

Start time

start_time

Filled out only for the first order. The start time to be used for this route. You may leave it blank, then the time is selected based on the other planning parameters.

No

Contact support