TomTom Maps SDK for JavaScript

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. A call with a key that lacks the access rejects with INSUFFICIENT_PERMISSIONS, and the error names the API. See A key refused access.

calculateReachableRanges computes the area reachable from an origin within a travel time or distance budget, and returns one GeoJSON polygon per budget. Several budgets from one origin give concentric bands. calculateReachableRange computes a single range.

The demo below shows 10, 20 and 30 minutes of driving from two stations, drawn by the reachable ranges module in the map's own colours.

Budget types

Each range takes a budget of { type, value }:

budgetTypes and the BudgetType type list them. budgetUnits holds the unit of each. All three come from @tomtom-org/maps-sdk/core, so your own labels can read like the module's titles:

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

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

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];

const result = await calculateReachableRanges([
    { origin, budget: { type: 'timeMinutes', value: 10 } },
    { origin, budget: { type: 'timeMinutes', value: 20 } },
    { origin, budget: { type: 'timeMinutes', value: 30 } },
]);

const map = new TomTomMap({ mapLibre: { container: 'map', center: origin, zoom: 9 } });
const rangesModule = await ReachableRangesModule.create(map);
await rangesModule.show(result); // titled '30 min', '20 min', '10 min'

The same call runs in Node.js, with no map. One call can mix a time and a distance budget:

import { calculateReachableRanges, geocodeOne } from '@tomtom-org/maps-sdk/services';

const origin = await geocodeOne('Domplein 9, Utrecht');
const ranges = await calculateReachableRanges([
    { origin, budget: { type: 'timeMinutes', value: 30 } },
    { origin, budget: { type: 'distanceKM', value: 25 } },
]);

The Node.js reachable range example runs it and prints each polygon's vertex count and bounding box.

Range options

Besides vehicle, costModel and when, which work as in calculateRoute within the limits below, a range takes:

Display on the map

ReachableRangesModule draws the result unchanged. Its guide covers fill styles, band colours, titles, events and every setting.

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

Ranges that can't be calculated

If the service answers a range with a 4xx error, calculateReachableRanges skips it instead of rejecting the batch. The service answers a 400 with the API error code MAP_MATCHING_FAILURE for an origin it can't match to a road, such as a point at sea.

Cancelling a batch

calculateReachableRanges takes one signal for the whole batch as its second argument. Aborting it cancels the range in flight and skips the rest. 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);
};

Unsupported options

The types leave out these routing parameters. For untyped callers, validation rejects them instead of returning a range computed without them.

Parameter Use instead
vehicle.state.heading Omit it, or use calculateRoute, which accepts it
costModel.avoid: 'alreadyUsedRoads' Drop that entry. The other avoidables are accepted
costModel.avoidAreas Omit it. This endpoint can't avoid areas
when: { option: 'arriveBy' }, with a date or a localDateTime Use option: 'departAt' with the same time, or omit when entirely

API reference

Related guides and examples

Related guides

Related examples