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

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.

The demo below shows 10, 20 and 30 minutes of driving from two stations, drawn by ReachableRangesModule in the map's own colours; the Reachable ranges module guide covers how.

Budget types

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

budgetTypes lists them, as the BudgetType type does, and budgetUnits holds the unit each counts in. All three come from @tomtom-org/maps-sdk/core, so labelling a range of your own reads as the module's titles do:

import { budgetUnits } from '@tomtom-org/maps-sdk/core';

const title = `${budget.value} ${budgetUnits[budget.type]}`; // '30 min', '20 % remaining'

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

Example

import { ReachableRangesModule, TomTomMap } 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 ReachableRangesModule.create(map);
await rangesModule.show(result);

Display on the map

ReachableRangesModule draws what calculateReachableRanges returns, unchanged: each band titled from its budget, each origin's bands nested around it, and the bands coloured from the map's accent and land colours unless a palette sets your own. Its guide covers the fill styles, colours, labels, events and every setting of the module.

const ranges = await ReachableRangesModule.create(map, { fillStyle: 'inverted' });
await ranges.show(result);

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:

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

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

Parameter Use instead
vehicle.state.heading Omit it, or use calculateRoute, which accepts it
vehicle.preferences.chargingPreferences Omit them, or use calculateRoute, which plans charging stops
costModel.avoid: 'alreadyUsedRoads' Drop that one entry — the other avoidables are accepted
costModel.avoidAreas Omit it; this endpoint cannot avoid areas
when.arriveBy Use when.departAt, or omit when entirely

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

API reference

Related guides and examples

Related guides

Related examples