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

EV charging stations availability

Request Access

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

The EV Charging Stations Availability service adds real-time status to the charging stations the search services return: the status of each charging point, and counts per connector type and power level. Searching for stations needs no such access.

In the demo below, each searched station shows its free and total charging points under its pin; click one to list its connectors and charging points.

Basic usage

import { discoverPlaces, getPlacesWithEVAvailability } from '@tomtom-org/maps-sdk/services';

const stations = await discoverPlaces({
    geoBias: { position: [4.9041, 52.3676] }, // Amsterdam
    filters: { poiCategories: ['CHARGING_LOCATION'] },
    limit: 10,
});

const stationsWithAvailability = await getPlacesWithEVAvailability(stations);
Function Takes Resolves to
getPlacesWithEVAvailability A Places collection The same places, in order, each with availability where known
getPlaceWithEVAvailability One place The place with availability, or undefined
evChargingStationsAvailability { id }, a place's dataSources.chargingAvailability.id The availability record alone, no place

How many requests it sends

getPlacesWithEVAvailability sends one request per station, one after the other by default. maxConcurrentRequests lets more of them run at once; the places come back in their input order either way.

Each request counts against your API key's queries-per-second limit, so raise it only as far as your key allows. The SDK retries a rate-limited (429) request with backoff bounded by retry.timeoutMs, and a request still failing after that leaves its station with unknown availability.

const stationsWithAvailability = await getPlacesWithEVAvailability(stations, { maxConcurrentRequests: 4 });

Cancelling the availability calls

Pass a signal in the options when a newer search or a map move supersedes the run: aborting cancels the in-flight requests, skips the remaining stations and rejects the call with an SDKAbortError, as for any other service call. A cancellation is the one failure that rejects.

createLatestRequest keeps only the newest run: starting one stops the previous one working through its list.

import { createLatestRequest, getPlacesWithEVAvailability } from '@tomtom-org/maps-sdk/services';

const latestAvailability = createLatestRequest();

const showAvailability = async (stations) => {
    const availability = await latestAvailability.run((signal) =>
        getPlacesWithEVAvailability(stations, { signal })
    );
    if (availability.current) await placesModule.show(availability.value);
};

Individual station availability

getPlaceWithEVAvailability takes one station, such as the one a user clicked:

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

const stationWithAvailability = await getPlaceWithEVAvailability(stations.features[0]);
if (stationWithAvailability) {
    const { count, statusCounts } = stationWithAvailability.properties.chargingPark.availability.chargingPointAvailability;
    console.log(`${statusCounts.Available ?? 0} of ${count} charging points available`);
}

Charging stations and points on search results

An EV search result already describes its hardware in place.properties.chargingPark, without real-time status; EV charging stations lists its fields. Only one of a charging point's connectors can charge at a time.

const { chargingPark } = stations.features[0].properties;

chargingPark?.connectors.forEach(({ connector, count }) => {
    console.log(`${count} × ${connector.type}, ${connector.ratedPowerKW} kW (${connector.chargingSpeed})`);
});

chargingPark?.chargingStations?.forEach((chargingStation) => {
    chargingStation.chargingPoints.forEach((point) => {
        const plugs = point.connectors?.map((connector) => connector.type).join(' or ');
        console.log(`${point.evseId ?? chargingStation.id}: ${plugs}`);
        if (point.capabilities.includes('PlugAndCharge')) console.log('  Plug & Charge');
        if (point.restrictions.includes('Customers')) console.log('  customers only');
    });
});

Understanding availability data

The availability lands in chargingPark.availability. A place with no chargingPark of its own, such as a route charging stop, also gets chargingPark.connectors, counted from the availability, but no static chargingStations:

Guard each station of a getPlacesWithEVAvailability result with hasChargingAvailability, since one whose availability is unknown comes back unchanged:

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

stationsWithAvailability.features.forEach((station) => {
    const { chargingPark } = station.properties;
    if (!hasChargingAvailability(chargingPark)) return;

    const { accessType, connectorAvailabilities, chargingStations } = chargingPark.availability;
    console.log(`Access: ${accessType}`);

    connectorAvailabilities.forEach(({ connector, count, statusCounts }) => {
        console.log(`${connector.type}, ${connector.ratedPowerKW} kW: ${statusCounts.Available ?? 0}/${count} available`);
    });

    chargingStations.forEach((chargingStation) => {
        chargingStation.chargingPoints.forEach((point) => {
            console.log(`${point.evseId ?? chargingStation.id}: ${point.status}`);
        });
    });
});

Integration with map display

The Places module shows the result as it is. With evAvailability.visible set, it labels each station with its available and total charging points, green when the available share reaches threshold (default 0.3) and red below it; the station's pin follows the same threshold. Both are knobs in the places knob catalogue.

import { PlacesModule } from '@tomtom-org/maps-sdk/map';

const placesModule = await PlacesModule.create(map, {
    evAvailability: {
        visible: true,
        threshold: 0.3,
        formatText: (available, total) => `${available} of ${total} free`, // default: `${available}/${total}`
    },
});

await placesModule.show(stationsWithAvailability);

Filtering by connector type

Keep the stations with a free connector of the types your vehicle takes:

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

const hasFreeConnector = (station, connectorTypes) =>
    hasChargingAvailability(station.properties.chargingPark) &&
    station.properties.chargingPark.availability.connectorAvailabilities.some(
        ({ connector, statusCounts }) => connectorTypes.includes(connector.type) && (statusCounts.Available ?? 0) > 0,
    );

const compatibleStations = {
    ...stationsWithAvailability,
    features: stationsWithAvailability.features.filter((station) =>
        hasFreeConnector(station, ['IEC62196Type2CCS', 'Chademo']),
    ),
};

To search only for stations with those connectors in the first place, pass them as the search's filters.connectors.

Related guides and examples

Related guides

Related examples