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.

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