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.9, 52.37];

// 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 budget, ordered largest first
// 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 labels from each feature's budget property automatically and styles each band by its fill style. Pass a palette and fill style to customise:

reachableRangeGeometryConfig('teal', 'outline')

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: { color: 'blues' } });
await module.show({ type: 'FeatureCollection', features });

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