3. Defining vehicles

Manage the fleet

Vehicle configuration

An important consideration to take into account, when optimizing routes is the fleet of vehicles that are available when planing a route. This information can be given to the API in the calcroute endpoint or setup in the master data. Let's consider the data structure in isolation and add a vehicle to the database via the /vehicle endpoint.

{"name": "vehname1",
 "plate": "MUC1",
 "driver_id": null,

 "capacity_1": 500,
 "capacity_2": 300,
 "capacity_3": 200,
 "daily_rate": 50.0,
 "km_rate": 0.40,
 "traveltime_factor": 1.0,

 "departure_time_from": "2022-07-03T09:30:00+00:00",
 "departure_time_to":   "2022-07-03T0:00:00+00:00",
 "return_time_to":      "2022-07-03T21:00:00+00:00",
 "max_tour_duration": 600,
 "depot_location_id": 1,
"default_adr_allowed": False

The vehicle has a mandatory unique name.
The depot_location_id defines where the tour starts for this particular vehicle. In case it's not assigned, the default depot is used.


The three capacities capacity_1, capacity_2 and capacity_3 define the maximum loads of a vehicle corresponding to the three load dimensions load, load_2 and load_3 (or loads=[] if you define load on items level), given in the individual deliveries. They can be of any dimension of your choice, e.g. weight in grams or kg, volume or loading meter, just be aware that they need to be integers, as required by the routing algorithm,
so please choose a unit that is small enough to resolve your required precision, as digits after the comma get cut off.
This is the relation between dimensions, load and load units: You define the dimensions and send the corresponding values with the shipments either on shipment level or on items level. If you have to transform loads by a factor, you add load units. The resulting values are compared with the vehicle capacity during the optimization. A vehicle could be full if one of the dimensions reached its capacity, e.g. max. number of pallet places or max. weight or max. ADR points.


The daily_rate and km_rate define two important parameters used in the cost function: they are supposed to be as small a possible, taking into account the given constraints. The daily_rate defines the fixed cost of the vehicle, which is basically the cost for a vehicle to be used at all. The km_rate defines the variable cost of the vehicle, payed for each kilometer driven. To be correct, we actually optimize routes for the shortest time, not driving distance. This often also results in a more ecological footprint, but the two not necessarily relate one on one. It might be worth noting, that the ratio between the daily_rate and the km_rate can in some circumstances have strong effect, on how many vehicles are used for a tour. They are in arbitrary units, e.g. $ or € - just make sure you keep it consistent.

Travel time

The traveltime_factor factor multiplied to the vehicle speed. The base speed depends on the vehicle_class, which can be one of car, truck, van, bike, walk. It also defines which roads can be driven (e.g. no trucks on a bike lane ...).

Departure time

The next set of parameters define the time frame of a tour. departure_time_from and departure_time_to set the time-window between which a driver is supposed to leave at the startaddress/depot. The max_tour_duration and return_time_to define the length of the tour. The two values introduce some flexibility: While the former defines the actual length of the tour, the latter defines the latest point in time of the end of the tour. With a varying start time, the two can turn out quite different. If both are given, the more restrictive is used.

for the return time to the depot/final destination, you can either define a point in time: the return_time or a time range with return_time_from and return_time_to, depending on your requirements.


You can enable the vehicle to carry dangerous goods and count ADR points.