Reachable ranges

Request Access

Important note Calculate Reachable Range is in Private Preview and unavailable on a Freemium or Pay As You Grow (PAYG) basis. Your API key needs access to it, and its API documentation requires a TomTom enterprise login. Click the Request Access button above to contact our Sales team.

calculateReachableRanges computes the geographic area reachable from a given origin within a specified budget — such as travel time, distance, or EV charge — and returns GeoJSON polygon features representing the reachable area for each budget value. Multiple budgets in a single call produce concentric rings.

Budget types

Each call requires a budget that defines what constrains the reachable area:

• timeMinutes – Area reachable within a given travel time (minutes)
• distanceKM – Area reachable within a given distance (kilometres)
• remainingChargePCT – Area reachable with at least X% charge remaining
• spentChargePCT – Area reachable spending at most X% of charge
• spentFuelLiters – Area reachable spending at most X litres of fuel

Both charge budgets are a percentage of the battery, so they need a capacity to convert against (see Vehicle Configuration):

• vehicle.engineType: 'electric' and vehicle.model.engine.charging.maxChargeKWH. A predefined model.variantId keeps its battery model on the service, so budget a variant by time or distance.
• For remainingChargePCT, also the charge the vehicle sets off with, in vehicle.state.

Example

import { GeometriesModule, TomTomMap, reachableRangeGeometryConfig } from '@tomtom-org/maps-sdk/map';
import { calculateReachableRanges } from '@tomtom-org/maps-sdk/services';

const origin: [number, number] = [4.9041, 52.3676];

// Calculate three concentric time-budget rings
const result = await calculateReachableRanges([
    { origin, budget: { type: 'timeMinutes', value: 10 } },
    { origin, budget: { type: 'timeMinutes', value: 20 } },
    { origin, budget: { type: 'timeMinutes', value: 30 } },
]);

// result.features — one PolygonFeature per range the service could calculate, in request order
// result.bbox     — bounding box covering all features
// feature.properties — the request it was calculated with (origin, budget, …), minus the API key and other common service params

// Display on map — labels ('30 min', '20 min', '10 min') applied automatically
const map = new TomTomMap({ mapLibre: { container: 'map', center: origin, zoom: 9 } });
const rangesModule = await GeometriesModule.create(map, reachableRangeGeometryConfig());
await rangesModule.show(result);

reachableRangeGeometryConfig derives each band's title from its feature's budget property automatically and styles each band by its fill style. Its options set the palette, the fill style, the layer position and a title of your own:

reachableRangeGeometryConfig({ palette: 'cold', fillStyle: 'outline' });

reachableRangeGeometryConfig({
    beforeLayerConfig: 'top',
    title: (feature, index) => `Zone ${index + 1}`,
});

prepareReachableRangesForDisplay(result, { fillStyle, title }) does the same preparation for a module configured by hand.

Available fill styles: 'filled' (default), 'outline', 'inverted'. See Geometry Module for more on display configuration.

Manual control

For full control, bypass reachableRangeGeometryConfig and set properties directly on each feature:

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

const features = result.features.map((f, i) => ({
    ...f,
    properties: {
        ...f.properties,
        title: `Zone ${i + 1}`,  // custom label
        fillStyle: 'inverted',   // 'filled' | 'outline' | 'inverted'
    },
}));

const module = await GeometriesModule.create(map, { fill: { palette: 'blues' } });
await module.show({ type: 'FeatureCollection', features });

Ranges that can't be calculated

calculateReachableRanges skips a range the service answers with an error rather than rejecting the batch. An origin the service can't match to a drivable road, such as a pedestrian square or a point on water, answers NO_RANGE_FOUND:

• result.features can be shorter than the request array, or empty. Match each feature to its request through properties.budget and properties.origin, and treat an empty result as "no range from this origin".
• calculateReachableRange, for a single range, rejects with that error instead.
• A 401, 403 or 429 response, an aborted signal and an invalid request reject the batch.

Cancelling a batch

calculateReachableRanges takes one signal for the whole batch as its second argument. When a new origin replaces the previous one, run the batch through createLatestRequest, as the reachable ranges example does on every map click:

import type { HasLngLat } from '@tomtom-org/maps-sdk/core';
import { calculateReachableRanges, createLatestRequest } from '@tomtom-org/maps-sdk/services';

const latestRanges = createLatestRequest();

const showRanges = async (origin: HasLngLat) => {
    const ranges = await latestRanges.run((signal) =>
        calculateReachableRanges(
            [10, 20, 30].map((value) => ({ origin, budget: { type: 'timeMinutes', value } })),
            { signal },
        ),
    );
    if (!ranges.current) return; // a newer origin retired this batch

    await rangesModule.show(ranges.value);
};

See Keeping only the latest request for what a retired batch resolves to.

Unsupported options

All budgets in a single calculateReachableRanges call must share the same origin and budget type.

The SDK rejects these routing parameters at the call, rather than returning a range computed without them:

The rest of vehicle, costModel and when works as it does in calculateRoute.

API reference

• calculateReachableRanges – Service function
• ReachableRangeParams – Request parameters
• ReachableRangeProperties – Properties of each result polygon
• reachableRangeGeometryConfig – Map display config factory
• Calculate Reachable Range API – API documentation (requires an enterprise login)

Related guides and examples

Related guides

• Vehicle Configuration – EV parameters for charge-based budgets
• Long Distance EV Routing – Route calculation with charging stops
• Geometry Module – Displaying polygon geometries on the map