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

Routing quickstart

The Routing Service calculates routes between locations with support for multiple waypoints, various vehicle types, and real-time traffic integration.

Initialization

Configure the SDK with your API key:

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

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

Calculating a route

Calculate a route between two locations:

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

Calculate a route between two geocoded locations:

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

const waypoints = await Promise.all([
  geocodeOne('Amsterdam, Netherlands'),
  geocodeOne('Paris, France')
]);

const route = await calculateRoute({ locations: waypoints });

Calculate a route with extra options:

const routes = await calculateRoute({
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
    costModel: {
        avoid: ['tollRoads'],
    },
    when: {
        option: 'departAt',
        date: new Date(Date.now() + 15 * 60 * 1000), // 15 minutes from now
    },
    maxAlternatives: 2
});

Accessing route information

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

console.log(`Distance: ${route.features[0].properties.summary.lengthInMeters}m`);
console.log(`Duration: ${route.features[0].properties.summary.travelTimeInSeconds}s`);

Showing a route on the map

Display the calculated route using the Routing Module:

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

// Initialize map
const map = new TomTomMap({ mapLibre: { container: 'map' } });

// Initialize Routing Module
const routingModule = await RoutingModule.create(map);


// Calculate route
const route = await calculateRoute({
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]]
});

// Display on map
await routingModule.showRoutes(route);

Planning again on every change

When a moved waypoint, a picked route 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);
};

See Keeping only the latest request for what a retired plan resolves to.

API reference

For complete documentation of all route calculation properties and types, see the calculateRoute API Reference.

Related guides and examples

Related guides

Map integration

Related examples