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

Route planning parameters

Route planning involves configuring parameters to calculate optimal routes between locations. This guide covers all available options for customizing route calculation.

Locations

For comprehensive guide on specifying route planning locations, see Locations.

Ordered list of locations for route calculation. Locations can be specified as single point waypoints or path arrays.

Calculate a route between two locations:

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

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

Calculate a route following a specific path using path arrays:

const route = await calculateRoute({
    locations: [
        [4.9, 52.3],  // Origin waypoint
        [
            [4.85, 52.25],  // Path points
            [4.80, 52.20],
            [4.75, 52.15]
        ],
        [4.5, 51.9]   // Destination waypoint
    ]
});

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 });

Alternative routes

Request multiple route options with maxAlternatives.

Alternative routes provide different travel options between the same origin and destination. Each alternative is optimized differently (e.g., avoiding highways, minimizing tolls). The best route is always returned as the first option.

Note: May return fewer alternatives than requested if not enough viable routes found.

Note: Increasing alternatives amount also increases response time.

const routes = await calculateRoute({
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],

    // Returns up to 3 routes total (best + 2 alternatives)
    maxAlternatives: 2
});

Cost model

Configure route type, traffic consideration, and avoidances using costModel.

routeType – Type of route optimization

traffic – What traffic data to consider for route planning

avoid – Route features to try to avoid (none by default)

avoidAreas – Rectangular geographic areas for the routing engine to bypass, expressed as GeoJSON bounding boxes [west, south, east, north] (up to 10)

// Fast route considering live traffic
const route = await calculateRoute({
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
    costModel: {
        routeType: 'fast', // default
        traffic: 'live' // default
    }
});

// Short route avoiding tolls
const route = await calculateRoute({
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
    costModel: {
        routeType: 'short',
        avoid: ['tollRoads']
    }
});

// Efficient route avoiding highways and ferries
const route = await calculateRoute({
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
    costModel: {
        routeType: 'efficient',
        traffic: 'historical',
        avoid: ['motorways', 'ferries']
    }
});

// Route bypassing a specific geographic area (e.g., a construction zone)
const route = await calculateRoute({
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
    costModel: {
        avoidAreas: [
            [2.265938, 48.81851, 2.41115, 48.90309] // [west, south, east, north]
        ]
    }
});

Departure and arrival time

Control when to depart or arrive using when.

The response will contain estimated departure and arrival times based on the provided parameters at summary.departureTime and summary.arrivalTime.

// Depart at specific time
const route = await calculateRoute({
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
    when: {
        option: 'departAt',
        date: new Date('2025-12-25T09:00:00Z')
    }
});

// Arrive by specific time
const route = await calculateRoute({
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
    when: {
        option: 'arriveBy',
        date: new Date('2025-12-25T17:00:00Z')
    }
});

Vehicle configuration

For comprehensive guide on specifying vehicle configuration, see Vehicle Configuration.

Configure vehicle-specific routing with the vehicle parameter.

model – vehicle weight and engine details. No other dimension: see Truck parameters

state – current vehicle state (fuel/charge levels)

restrictions – maximum speed and toll transponder

preferences – charging preferences (electric vehicles only)

Setting vehicle.preferences.chargingPreferences selects the Long Distance EV Routing endpoint, where the top-level chargingStopsStrategy parameter chooses how charging stops are picked. See Long Distance EV Routing.

// Generic vehicle
const route = await calculateRoute({
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
    vehicle: {
        model: {
            dimensions: {
                weightKG: 3500
            }
        }
    }
});

Turn-by-turn guidance

For comprehensive guide on guidance instructions, see Guidance.

Request turn-by-turn instructions:

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

Route sections

Request specific section to be included in the route response. Leg sections are always included.

Route section types: carpool, carTrain, country, ferry, importantRoadStretch, lanes, leg, lowEmissionZone, motorway, pedestrian, roadShields, speedLimit, toll, tollRoad, tollVignette, traffic, tunnel, unpaved, urban, vehicleRestricted, Includes all available section types by default.

const route = await calculateRoute({
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
    sectionTypes: ['toll', 'ferry', 'traffic', 'motorway', 'country']
});

See the full list of available section types in the Route Object Guide.

Extended route information

Include progress data at route polyline points (enabled by default). The resulting route object will contain an additional property "progress" containing arrays of cumulative values for each point of the route.

Useful for displaying progress during navigation.

const route = await calculateRoute({
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
    extendedRouteRepresentations: ['distance', 'travelTime'] // default
});

Traffic-based travel times

Compare travel times across different traffic scenarios.

none – only current traffic travel time is returned (default)

all – the returned route summary will contain extra fields:

Useful for comparing traffic impact and displaying "X minutes saved by leaving now".

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

Per-stop options

Any waypoint can carry its own options in properties, typed with RouteStopOptions. They describe the leg arriving at that stop plus the wait once there, so inserting an earlier stop later on leaves them attached to the right place.

const route = await calculateRoute({
    locations: [
        [2.1734, 41.3851],
        {
            type: 'Feature',
            geometry: { type: 'Point', coordinates: [2.4467, 41.5381] },
            properties: {
                pauseDurationSeconds: 1800,
                legCostModel: { routeType: 'short', avoid: ['motorways'] }
            }
        },
        [2.8214, 41.9794]
    ]
});

Arrival side

Which side of the road to arrive on, at the destination and at every intermediate stop:

any – arrive from either side, whichever is faster (default) curb – arrive on the curb side for the country's driving direction

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

Entry points

Control how building entry points are used:

main-when-available – routes to main entrance when available (default) ignore – use place center position

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

For a stop with several usable entrances, candidateEntryPoints above hands the alternatives to the routing engine instead of resolving one position client-side.

A parameter the endpoint cannot accept

calculateRoute() covers two endpoints — a plain route and the long-distance EV route it switches to when you set vehicle.preferences.chargingPreferences — and calculateReachableRange() a third. They do not all accept the same parameters.

The SDK never sends one the endpoint would reject, and never drops it silently either. It does one of two things:

The failure it exists to prevent is the silent one: a request that drops an input still returns a route, with plausible numbers, computed from something other than what you asked for.

API reference

For complete documentation of all route calculation parameters and types, see the CalculateRouteParams API Reference.

Related guides and examples

Related guides

Related examples

Map integration

Related services