Vehicle Parameters

The Routing API offers a detailed parameterization in case the vehicle used does not correspond to one of the predefined profiles. Note that the values of the predefined profiles may be adapted to reflect current vehicle standards. To obtain the same results when values change, it is recommended to always send with the request the vehicle parameters that are important for your use case.

In the following sections it is explained which vehicle parameters are related to each other.

Engine type

The Routing API supports different engine types, the user can select one of the available engine types: COMBUSTION, HYBRID or ELECTRIC. Depending on the chosen engine type, several other vehicle parameters must be defined to better match the vehicle specific configuration.

Engine type `COMBUSTION`

Engine type COMBUSTION requires fuelType and averageFuelConsumption to be specified.

Engine type `ELECTRIC`

Engine type ELECTRIC requires electricityType and averageElectricityConsumption to be specified.

Engine type `HYBRID`

Engine type HYBRID requires hybridRatio and all required parameters of COMBUSTION and ELECTRIC to be specified.

Whenever such a parameter is missing, a warning will be returned with the warning code ROUTING_MISSING_VEHICLE_PARAMETER. We recommend always to specify all relevant vehicle parameters, otherwise results like emissions, toll, or the monetary cost report may be incomplete or contain wrong results.

When specifying a parameter not supported by the engine type, a warning with the warning code GENERAL_PARAMETER_IGNORED will be returned. This warning has no effect on the response, but the parameter in question should be removed from the request.

Fuel type

The fuel types CNG_GASOLINE and LPG_GASOLINE require the dualFuelRatio to be specified, and these fuel types are only allowed for engineType COMBUSTION.

The bioFuelRatio is supported ony for the fuelTypes DIESEL, GASOLINE, CNG_GASOLINE or LPG_GASOLINE.

For ETHANOL the bioFuelRatio is ignored, ethanol is always assumed to be 100% bio fuel.

Fuel consumption

The engine's averageFuelConsumption denotes the effective fuel consumed by the vehicle per 100km. Depending on the fuelType, it should be expressed in the following units:

l/100km : for fuel types DIESEL, GASOLINE, LIQUEFIED_PETROLEUM_GAS, LPG_GASOLINE and ETHANOL.
kg/100km : for fuel types COMPRESSED_NATURAL_GAS, LIQUEFIED_NATURAL_GAS and CNG_GASOLINE.

Engines that can operate using a mixture of two different fuels are called dual fuel engines. The Routing API supports LPG_GASOLINE and CNG_GASOLINE along with the dualFuelRatio. This ratio denotes the consumption of CNG/LPG fuel type from the total amount of the vehicle consumption per 100km.

For LPG_GASOLINE, the fuel consumption should be given as l/100km and can be computed as following :

averageFuelConsumption_{LPG_GASOLINE [l/100km]} = averageFuelConsumption_{LIQUEFIED_PETROLEUM_GAS [l/100km]} + averageFuelConsumption_{GASOLINE [l/100km]}
dualFuelRatio = averageFuelConsumption_{LIQUEFIED_PETROLEUM_GAS [l/100km]} / averageFuelConsumption_{LPG_GASOLINE [l/100km]}

For CNG_GASOLINE, the fuel consumption should be given as kg/100km and can be computed as following :

averageFuelConsumption_{CNG_GASOLINE [kg/100km]} = averageFuelConsumption_{COMPRESSED_NATURAL_GAS [kg/100km]} + density_{GASOLINE [kg/l]} * averageFuelConsumption_{GASOLINE [l/100km]}
with density_{GASOLINE [kg/l]} = 0.743
and dualFuelRatio = averageFuelConsumption_{COMPRESSED_NATURAL_GAS [kg/100km]} / averageFuelConsumption_{CNG_GASOLINE [kg/100km]} .

Engine type related parameters

Engine Parameter/EngineType	`COMBUSTION`	`HYBRID`	`ELECTRIC`
fuelType	All values except `NONE`	All fuel types except `NONE`, `CNG_GASOLINE` and `LPG_GASOLINE`	`NONE`
electricityType	`NONE`	All values except `NONE`	All values except `NONE`
bioFuelRatio	Any value between 0, 100 (inclusive), only if fuelType is `DIESEL`, `GASOLINE`, `CNG_GASOLINE` or `LPG_GASOLINE`	Any value between 0, 100 (inclusive), only if fuelType is `DIESEL` or `GASOLINE`	0
hybridRatio	0	Any value comprised between 0, 100 (exclusive)	0
dualFuelRatio	Any value between 0, 100 (exclusive), only if fuelType is either `CNG_GASOLINE` or `LPG_GASOLINE`	0	0
averageFuelConsumption	Any value greater than 0	Any value greater than 0	0
averageElectricityConsumption	0	Any value greater than 0	Any value greater than 0
particleReductionClass	All values	All values	`NONE`
emissionStandard	All values	All values	`NONE`
cylinderCapacity	Any value greater than 0	Any value greater than 0	0

Weight parameters

There are parameters for the actual weight and the permitted weight of the whole vehicle:

The actual weight is the sum of emptyWeight and loadWeight.
For the permitted weight there are two variants: totalPermittedWeight and totalTechnicallyPermittedWeight. Often these two values are the same, only for toll calculation there are cases when it is important to set different values, see the concept on toll. To avoid inconsistent settings there is a special logic implemented concerning the default: The default is the value of the other permitted weight parameter - if only one of the two permitted weight parameters is set, the other permitted weight parameter is also set to that value. For example, if the predefined profile specifies a total technically permitted weight of 12.5t and a total permitted weight of 12t, and in the request only the total permitted weight is set to 18t, then the effective total technically permitted weight is also 18t. Hence, if it is desired to have different permitted weight values, both permitted weight parameters have to be specified.

Normally the actual weight should be less than or equal to the totalPermittedWeight and the totalPermittedWeight should be less than or equal to the totalTechnicallyPermittedWeight.