TomTom Maps SDK for JavaScript
This is the documentation of version 0.63.0. Go to the latest version, 1.0.0-rc.5.

Long distance EV routing

Request Access

Important note Long Distance EV Routing is unavailable on a Freemium or Pay As You Grow (PAYG) basis. Click the Request Access button above to contact our Sales team.

Long Distance EV Routing calculates routes for electric vehicles on extended journeys. When you provide an electric vehicle configuration with charging preferences, the calculateRoute method automatically calculates energy consumption, determines optimal charging stop locations, estimates charging time at each stop, and returns an extended route with additional legs for each charging stop.

Activation

Long Distance EV Routing is activated when you provide:

Optionally, chargingStopsStrategy selects how the stops are chosen:

It is only accepted alongside vehicle.preferences.chargingPreferences, because this endpoint also needs a minimum charge at the destination and only the preferences provide it. The types enforce the pairing: asking for a strategy requires a vehicle of type ElectricVehicleParamsWithChargingStops, so setting the strategy on its own does not compile.

A predefined vehicle.model.variantId is bound to the same endpoint, and so carries the same requirement — enforced at validation here rather than by the type, because calculateReachableRange takes the same vehicle and accepts a variant on its own. Non-electric vehicles take no variantId at all — describe them with model.dimensions and model.engine.

Additionally, these vehicle model parameters become required:

See Vehicle Configuration for the full EV configuration details.

Response structure

See Route Object for the base route structure details.

Routes with charging stops contain additional information:

Route Summary:

Each Leg:

Each Leg Summary:

Charging Stop Leg Summary:

Time spent at a charging stop

Charging stops are chosen by the service, so they are not waypoints you can attach options to — pauseDurationSeconds applies to your stops. What you can set is how much time every charging stop takes on top of the charging itself, through the charging model:

vehicle: {
    engineType: 'electric',
    model: { engine: { charging: {
        // 15 minutes per stop for parking, plugging in and paying (default 60 seconds)
        chargingTimeOffsetInSec: 900
    } } }
}

The offset is included in the chargingTimeInSeconds the response reports for each stop, and in totalChargingTimeInSeconds. How long the charging part itself takes follows from the battery curve, the connectors and minChargeAtChargingStopsInkWh — raising the minimum charge takes more energy on board, and so more time.

A leg that ends at a charging stop reports the whole time there as stopTimeInSeconds, the same field a leg ending at one of your own waiting stops uses. On a route where nothing waits, that value equals the stop's chargingTimeInSeconds.

Example

import { calculateRoute } from '@tomtom-org/maps-sdk/services';

const result = await calculateRoute({
    locations: [
        [4.9041, 52.3676],  // Amsterdam
        [13.4050, 52.5200]  // Berlin (long distance)
    ],
    vehicle: {
        engineType: 'electric',
        model: {
            engine: {
                charging: {
                    maxChargeKWH: 75,
                    batteryCurve: [
                        { stateOfChargeInkWh: 50, maxPowerInkW: 200 },
                        { stateOfChargeInkWh: 70, maxPowerInkW: 100 },
                        { stateOfChargeInkWh: 80, maxPowerInkW: 40 },
                    ],
                    chargingConnectors: [
                        {
                            currentType: 'DC',
                            plugTypes: ['Combo_to_IEC_62196_Type_2_Base'],
                            efficiency: 0.9,
                            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
            }
        }
    }
});

// Route now contains charging stops
console.log(`Total legs: ${result.features[0].properties.sections.leg.length}`);
console.log(`Total charging time: ${result.features[0].properties.summary.totalChargingTimeInSeconds}s`);

Unsupported options

API reference

Related guides and examples

Related guides

Related examples