Basic definitions
To start planning routes, define a depot, vehicles, and orders for the same planning window.
This will give you optimal vehicle routes and metrics for analyzing the results.
Below we'll look at the main properties for depots, vehicles, and orders. For more information about the properties and optimization use cases, see Time window properties, Weight and volume properties, Vehicle properties, and Order properties.
Depot
A depot is a location where all routes can start and end. Orders are loaded into vehicles at the depot. You can only specify one depot per request. The depot's working hours must be specified. For a detailed description of the parameters, see Depot properties.
The depot is set in the depot field.
Vehicles
Orders can be delivered by regular vehicles or couriers traveling on foot or by public transit. Vehicles and couriers share the same set of properties.
Vehicles and couriers are set in the vehicles field.
Vehicle capacity
You can define a vehicle's volume capacity or weight capacity. Specify them in the request. Otherwise, the algorithm might build routes with overloaded vehicles.
A vehicle's load capacity is set in the vehicle.capacity field.
Orders
Orders are the locations where cargo is to be delivered. For each order, you must specify its geographical coordinates and a time window.
Orders are set in the locations field.
Order coordinates
The order location is set as the geographical coordinates of the parking or stop location at the order address.
If the order location in your system is specified with an address, geocode it (convert an address from text format to geographical coordinates).
Order coordinates are set in the location.point field.
Order time window
Specify a time window for all orders. This is the time window when the vehicle or courier must arrive at the order address.
The order time window is set in the location.time_window field.
Order handling time
You can define the amount of time it takes to hand each order over to the client. This time includes everything that the vehicle or courier does after arriving at the order address but before departing for the next order, such as parking and physically delivering the order.
The handling time is set in the location.service_duration_s field, in seconds.
Order weight
You can specify the weight of each order. This isn't required, but we recommend it to avoid overloading vehicles.
The order weight is set in the location.shipment_size field.
Routes
The service creates routes: sequences of order deliveries for each vehicle with an estimated arrival time for each order location.
Routes are given in the routes field of the response.
Metrics
In addition to optimized routes, the service response includes metrics to analyze planning performance. These include the total distance and time on routes, the number and absolute time of delays, and more.
The metrics are calculated both for all routes together and each route separately and are returned in the metrics response field.
Route cost
Optimization minimizes the cost of routes. The cost consists of the following parameters:
-
The total cost of all vehicles (per kilometer, hour, and the fact of using the vehicle).
-
The total penalties for violations of business restrictions (penalties for not delivering an order, time window violation, and others).
The cost is calculated both for all routes together and each route separately and is returned in the metrics field of the response.