Vehicle configuration

Configure vehicle-specific routing with the vehicle parameter.

Parameters

model (predefined)

variantId – Predefined vehicle model ID from TomTom database (contact support for available models). Only electric vehicles have one. On calculateRoute it needs preferences.chargingPreferences beside it, because only the charging-stops endpoint looks a variant up; on calculateReachableRange it stands on its own.

model (manual)

dimensions – Object with weightKG
engineType – 'combustion' / 'electric' / not specified
engine – Engine model (only if engineType is specified)
- Combustion: consumption (fuelEnergyDensityInMJoulesPerLiter, speedToConsumption, auxiliaryPowerInLitersPerHour)
- Electric: consumption (speedToConsumption, auxiliaryPowerInkW, recuperationInKWHPerKMAltitudeLoss, consumptionInKWHPerKMAltitudeGain), charging (maxChargeKWH, chargingCurve, chargingConnectors, chargingTimeOffsetInSec, batteryCurve)

state

Any vehicle, on calculateRoute: heading – Heading at the origin, in degrees clockwise from true North
Combustion vehicles: currentFuelInLiters
Electric vehicles: currentChargePCT, currentChargeInkWh

restrictions

maxSpeedKMH – Maximum speed in km/h
tollTransponder – Whether the vehicle carries an electronic toll collection transponder (all, unknown or none). Affects which tolls are treated as usable: tolls payable only by transponder are avoided with none, and tolls that cannot be paid by one are avoided with all.

preferences (electric vehicles on calculateRoute only):

chargingPreferences (minChargeAtDestinationPCT, minChargeAtChargingStopsPCT, minChargeAtDestinationInkWh, minChargeAtChargingStopsInkWh)

Providing preferences.chargingPreferences enables Long Distance EV Routing, which adds charging stops to the route as needed. calculateReachableRange plans no stops, so it takes no preferences at all.

See Long Distance EV Routing for more details.

Truck parameters

Routing on Orbis v3 plans routes for a car: travelMode takes 'car' only, and of a vehicle's dimensions it takes the weight alone. Each parameter below was sent on its own to all three endpoints — the route, the long-distance EV route and the reachable range — on 2026-09-01:

Parameter	Accepted	What the API answers
Weight — `model.dimensions.weightKG`	Yes	`200`
Maximum speed — `restrictions.maxSpeedKMH`	Yes	`200`
Length, width, height, axle weight	No	`400 Unknown JSON field`
Load type (hazardous materials), ADR tunnel restriction code	No	`400 Unknown JSON field`
Commercial vehicle	No	`400 Invalid boolean value` for anything but `false`, which restricts nothing
`travelMode: 'truck'`	No	`car` is the only travel mode

The SDK has none of the rejected parameters on its types, so a truck's dimensions fail to compile rather than return a car's route.
Spelling them another way does not help: v3 rejects any body field it does not know by name — vehicleHeight and vehicleHeightInMeters alike.
The rejections still held when the reachable range moved to v3, re-probed on 2026-09-15.

Model examples

Predefined model

const route = await calculateRoute({
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
    vehicle: {
        engineType: 'electric',
        model: {
            variantId: 'mercedes-eqv-300-2021'
        },
        state: { currentChargeInkWh: 60 },
        // The charging-stops endpoint is the only one that looks a variant up, and these select it
        preferences: {
            chargingPreferences: {
                minChargeAtDestinationInkWh: 15,
                minChargeAtChargingStopsInkWh: 10
            }
        }
    }
});

A reachable range takes the same variant with nothing beside it, since it plans no charging stops. Budget it by time or distance: a charge budget is a percentage of the battery, and the capacity to convert it against stays on the service rather than travelling in the request.

const ranges = await calculateReachableRanges([{
    origin: [4.9041, 52.3676],
    budget: { type: 'distanceKM', value: 150 },
    vehicle: {
        engineType: 'electric',
        model: { variantId: 'mercedes-eqv-300-2021' },
        state: { currentChargeInkWh: 60 }
    }
}]);

Generic vehicle example

const route = await calculateRoute({
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
    vehicle: {
        model: {
            dimensions: {
                weightKG: 3500
            }
        }
    }
});

Combustion vehicle example

const route = await calculateRoute({
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
    vehicle: {
        engineType: 'combustion',
        model: {
            dimensions: {
                weightKG: 1500
            },
            engine: {
                consumption: {
                    fuelEnergyDensityInMJoulesPerLiter: 34.2,
                    speedsToConsumptionsLiters: [
                        { speedKMH: 50, consumptionUnitsPer100KM: 6.5 },
                        { speedKMH: 90, consumptionUnitsPer100KM: 7.2 },
                        { speedKMH: 120, consumptionUnitsPer100KM: 9.0 }
                    ]
                }
            }
        },
        state: {
            currentFuelInLiters: 45
        }
    }
});

Electric vehicle example

const route = await calculateRoute({
    locations: [[4.9, 52.3], [8.5, 50.1]],
    vehicle: {
        engineType: 'electric',
        model: {
            dimensions: {
                weightKG: 2000
            },
            engine: {
                charging: {
                    maxChargeKWH: 75,
                    batteryCurve: [
                        { stateOfChargeInkWh: 50, maxPowerInkW: 200 },
                        { stateOfChargeInkWh: 70, maxPowerInkW: 100 },
                        { stateOfChargeInkWh: 80, maxPowerInkW: 40 },
                    ],
                    chargingConnectors: [
                        {
                            currentType: 'AC3',
                            plugTypes: [
                                'IEC_62196_Type_2_Outlet',
                                'IEC_62196_Type_2_Connector_Cable_Attached',
                                'Combo_to_IEC_62196_Type_2_Base',
                            ],
                            efficiency: 0.9,
                            baseLoadInkW: 0.2,
                            maxPowerInkW: 11,
                        },
                        {
                            currentType: 'DC',
                            plugTypes: [
                                'IEC_62196_Type_2_Outlet',
                                'IEC_62196_Type_2_Connector_Cable_Attached',
                                'Combo_to_IEC_62196_Type_2_Base',
                            ],
                            voltageRange: { minVoltageInV: 0, maxVoltageInV: 500 },
                            efficiency: 0.9,
                            baseLoadInkW: 0.2,
                            maxPowerInkW: 150,
                        },
                    ]
                },
                consumption: {
                    speedsToConsumptionsKWH: [
                        { speedKMH: 50, consumptionUnitsPer100KM: 15 },
                        { speedKMH: 90, consumptionUnitsPer100KM: 18 },
                        { speedKMH: 120, consumptionUnitsPer100KM: 23 }
                    ]
                }
            }
        },
        state: {
            currentChargePCT: 80
        },
        preferences: {
            chargingPreferences: {
                minChargeAtDestinationPCT: 20,
                minChargeAtChargingStopsPCT: 10
            }
        }
      }
});

API reference

For complete documentation of all route vehicle parameters and types, see the VehicleParameters API Reference.

Related guides and examples

Related guides

Routing Quickstart - Getting started with route calculation
Route Planning Parameters - Comprehensive route planning with configuration options
Long Distance EV Routing - In-depth guide to electric vehicle routing with charging stops

Map integration

Routing Module - Display calculated routes on map