Routing quickstart

calculateRoute plans a route through an ordered list of locations and returns it as GeoJSON: a FeatureCollection of route features, the best route first. It runs in the browser and in Node.js alike.

Initialization

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

TomTomConfig.instance.put({ apiKey: 'YOUR_API_KEY' });

The global configuration also sets the language and units every call uses.

Calculating a route

import { calculateRoute } from '@tomtom-org/maps-sdk/services';

const routes = await calculateRoute({
    locations: [
        [4.9041, 52.3676], // Amsterdam
        [2.3522, 48.8566]  // Paris
    ]
});

Locations take coordinates, geocoding and search results, or a previous route — see Locations.
Everything else — cost model, departure time, alternatives, sections, guidance — is in Route planning parameters, with the vehicle in Vehicle configuration.

Accessing route information

const { summary } = routes.features[0].properties;

console.log(`Distance: ${summary.lengthInMeters} m`);
console.log(`Duration: ${summary.travelTimeInSeconds} s`);

The route object lists the summary, sections, guidance and progress fields; What the routing SDK adds lists the ones the SDK derives on top of the API.

Showing a route on the map

RoutingModule.showRoutes takes the response unchanged:

import { TomTomMap, RoutingModule } from '@tomtom-org/maps-sdk/map';
import { calculateRoute } from '@tomtom-org/maps-sdk/services';

const map = new TomTomMap({ mapLibre: { container: 'map' } });
const routingModule = await RoutingModule.create(map);

const locations = [[4.9041, 52.3676], [2.3522, 48.8566]];
const routes = await calculateRoute({ locations });

await routingModule.showRoutes(routes);
await routingModule.showWaypoints(locations);

Displaying routes covers the module: selection, waypoints, events and sections.

Planning again on every change

When a moved waypoint or a toggled option plans the route again, a slow earlier plan can land after a newer one and draw a stale route. Run each plan through createLatestRequest, as the route sections playground does:

import { calculateRoute, createLatestRequest } from '@tomtom-org/maps-sdk/services';

const latestPlan = createLatestRequest();

const showRoute = async (locations) => {
    const plan = await latestPlan.run((signal) => calculateRoute({ locations, signal }));
    if (!plan.current) return; // a newer change retired this plan

    await routingModule.showWaypoints(locations);
    await routingModule.showRoutes(plan.value);
};

API reference

Related guides and examples

Related guides

Route planning parameters – Every option calculateRoute takes
Locations – Waypoints, paths and per-stop options
Route object – The shape of the response
Long distance EV routing – Electric routes with charging stops
Request options and errors – Validation, cancelling and errors, shared by every service

Map integration

Displaying routes – RoutingModule

Related examples

Route with waypoints – Basic route calculation and display
Route with alternatives – Several route options
Waypoints – Multi-stop routing
Route sections playground – A picked route retires the plan still in flight
Node.js routing – Server-side routing