Reachable Ranges

Important note Calculate Reachable Range is unavailable on a Freemium or Pay As You Grow (PAYG) basis. 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)
remainingChargeCPT – 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

EV budget types (remainingChargeCPT, spentChargePCT) require a full electric vehicle configuration. See Vehicle Configuration .

Example

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

4
const origin: [number, number] = [4.9, 52.37];
5

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

13
// result.features — one PolygonFeature per budget, ordered largest first
14
// result.bbox     — bounding box covering all features
15

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

reachableRangeGeometryConfig derives labels from each feature’s budget property automatically and applies themed styling. Pass a palette and theme to customise:

1
reachableRangeGeometryConfig('teal', 'outline')

Available themes: '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:

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

3
const features = result.features.map((f, i) => ({
4
    ...f,
5
    properties: {
6
        ...f.properties,
7
        title: `Zone ${i + 1}`,  // custom label
8
        theme: 'inverted',       // 'filled' | 'outline' | 'inverted'
9
    },
10
}));
11

12
const module = await GeometriesModule.get(map, { colorConfig: { fillColor: 'blues' } });
13
module.show({ type: 'FeatureCollection', features });

Unsupported options

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

API Reference

calculateReachableRanges – Service function
ReachableRangeParams – Request parameters
reachableRangeGeometryConfig – Map display config factory
Calculate Reachable Range API – API documentation

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