Vehicle configuration

vehicle describes what drives the route — its weight, engine, consumption, charge and restrictions. calculateRoute and calculateReachableRanges take the same object, with the exceptions below.

Parameters

engineType – 'combustion', 'electric', or unset for a generic vehicle. It decides which engine, state and preferences the vehicle takes.

model – Either a predefined model or a description:

• variantId – A vehicle from TomTom's database (contact support for the available ids). Electric vehicles only.
  • On calculateRoute it needs preferences.chargingPreferences beside it, because only the charging-stops endpoint looks a variant up.
• dimensions.weightKG – The only dimension routing takes; see Truck parameters.
• engine – Combustion and electric vehicles only; consumption is required once engine is set.
  • Combustion consumption: speedsToConsumptionsLiters (required, 1 to 25 points), auxiliaryPowerInLitersPerHour, fuelEnergyDensityInMJoulesPerLiter, efficiency.
  • Electric consumption: speedsToConsumptionsKWH (required, 1 to 25 points), auxiliaryPowerInkW, consumptionInKWHPerKMAltitudeGain with recuperationInKWHPerKMAltitudeLoss, efficiency.
  • efficiency, for either: acceleration with deceleration, and uphill with downhill, each from 0 to 1.
  • Electric charging: maxChargeKWH (required), batteryCurve (up to 20 points of stateOfChargeInkWh and maxPowerInkW), chargingConnectors (currentType, plugTypes, efficiency, baseLoadInkW, maxPowerInkW, maxVoltageInV, maxCurrentInA, voltageRange), and chargingTimeOffsetInSec (default 60).

state – What changes during the trip:

• heading – On calculateRoute only: the heading at the origin, in degrees clockwise from true North.
• Combustion: currentFuelInLiters.
• Electric: currentChargePCT or currentChargeInkWh.

restrictions

• maxSpeedKMH – 0 to 250; 0, the default, lets the router pick a value for the vehicle.
• tollTransponder – Whether the vehicle carries an electronic toll collection transponder: all, unknown (default) or none. 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 with minChargeAtChargingStopsPCT, or minChargeAtDestinationInkWh with minChargeAtChargingStopsInkWh. Setting them switches on Long distance EV routing, which adds charging stops.

Percentages — of charge, of charging preferences — are converted against maxChargeKWH, so a variantId, which declares none, takes the kWh forms.

Reachable ranges

calculateReachableRanges takes the same vehicle without state.heading and without preferences, since it plans no charging stops — so a variantId stands on its own there. Its charge budgets need maxChargeKWH; budget a variant by time or distance.

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:

• The SDK types have none of the rejected parameters, 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.

Model examples

Predefined model

const routes = await calculateRoute({
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
    vehicle: {
        engineType: 'electric',
        model: { variantId: '54B969E8-E28D-11EC-8FEA-0242AC120002' },
        state: { currentChargeInkWh: 60 },
        // Only the charging-stops endpoint 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:

const ranges = await calculateReachableRanges([{
    origin: [4.9041, 52.3676],
    budget: { type: 'distanceKM', value: 150 },
    vehicle: {
        engineType: 'electric',
        model: { variantId: '54B969E8-E28D-11EC-8FEA-0242AC120002' },
        state: { currentChargeInkWh: 60 }
    }
}]);

Generic vehicle example

const routes = await calculateRoute({
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
    vehicle: {
        model: { dimensions: { weightKG: 3500 } },
        restrictions: { maxSpeedKMH: 90, tollTransponder: 'none' }
    }
});

Combustion vehicle example

const routes = 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

With charging preferences, so the route gains charging stops:

const routes = 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

• VehicleParameters – The calculateRoute vehicle
• ReachableRangeVehicleParameters – The reachable range vehicle

Related guides and examples

Related guides

• Route planning parameters – Every other routing option
• Long distance EV routing – Electric routes with charging stops
• Reachable ranges – Fuel and charge budgets

Related examples

• Long Distance EV Routing with detailed vehicle – An electric vehicle described in full, on a map
• Long Distance EV Routing with model ID – A predefined variantId