TomTom Maps SDK for JavaScript
This is the documentation of version 0.64.0. 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 area reachable from an origin within a budget — travel time, distance, fuel or charge — and returns one GeoJSON polygon per budget. Several budgets from one origin give concentric bands; calculateReachableRange computes a single one.

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 lists them, as the BudgetType type does, and budgetUnits holds the unit each counts in — all from @tomtom-org/maps-sdk/core, so a label of your own reads like the module's titles:

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, described under 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];

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'

Range options

Beside vehicle, costModel and when, which work as on calculateRoute within the limits below:

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, { 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; 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 these routing parameters out, and validation rejects them for untyped callers, 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

API reference

Related guides and examples

Related guides

Related examples