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

Route planning parameters

calculateRoute takes these options besides its locations. All are optional, with the defaults given below.

Locations

locations is the only required parameter, the ordered waypoints and paths the route passes through. Locations covers every accepted form.

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

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

Alternative routes

maxAlternatives – 0 (default) to 5 alternatives on top of the best route, which always comes first.

const routes = await calculateRoute({
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
    maxAlternatives: 2 // up to 3 routes in total
});

Cost model

costModel decides which path wins.

routeType – What the route is optimised for:

traffic – Which traffic the route plans around:

avoid – What the route tries to avoid (nothing by default). If no other route exists, avoidance is not guaranteed:

avoidAreas – Up to 10 rectangles to bypass, each a bounding box [west, south, east, north] or any GeoJSON whose bounding box is the rectangle:

const routes = await calculateRoute({
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
    costModel: {
        routeType: 'efficient',
        traffic: 'historical',
        avoid: ['motorways', 'ferries'],
        avoidAreas: [[2.265938, 48.81851, 2.41115, 48.90309]] // around Paris
    }
});

A single leg can override routeType and avoid. See Per-stop options.

Departure and arrival time

when – Depart at, or arrive by, a given time (default: depart now). A past or unreachable time falls back to departing now. The response carries both times as summary.departureTime and summary.arrivalTime.

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

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

Vehicle configuration

vehicle – Weight, heading and restrictions, all listed in Vehicle configuration.

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

Turn-by-turn guidance

guidance: { type: 'coded' } adds instructions to each route. See Guidance.

Route sections

sectionTypes – Which sections the response carries. By default, it requests every type. A list narrows the response to those types, and [] asks for none.

Section type Requested
carpool, carTrain, country, ferry, importantRoadStretch, lowEmissionZone, motorway, pedestrian, roadShields, speedLimit, toll, tollRoad, tollVignette, traffic, tunnel, unpaved, urban, vehicleRestricted Through sectionTypes
lanes Only with guidance, and through sectionTypes when a list is given
leg Always 
const routes = await calculateRoute({
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
    sectionTypes: ['toll', 'ferry', 'traffic', 'motorway', 'country']
});

Extended route information

extendedRouteRepresentations – Cumulative distance and travel time at points along the route, in the route's progress property (default ['distance', 'travelTime']).

const routes = await calculateRoute({
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
    extendedRouteRepresentations: [] // no progress data
});

Traffic-based travel times

computeTravelTimeFor – 'none' (default), or 'all' for three more travel times in the summary, to show what traffic costs or what leaving now saves:

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

Per-stop options

Any waypoint feature carries its own options in properties, typed with RouteStopOptions. They describe the leg arriving at that stop and the wait there, so if you insert an earlier stop, they stay attached to the right place.

const routes = 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]
    ]
});

const legs = routes.features[0].properties.sections.leg;
legs[0].summary.stopTimeInSeconds;   // the whole time at the first stop
legs[0].summary.travelTimeInSeconds; // driving only

The wait comes back as the arriving leg's stopTimeInSeconds. Leg travel times are driving only, while the route's travel time includes every stop. What the routing SDK adds explains both.

Arrival side

arrivalSide – Which side of the road to arrive on, at the destination and every intermediate stop, as one of the importable arrivalSides:

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

Entry points

useEntryPoints – Where a place waypoint with entry points is routed to:

const routes = await calculateRoute({
    locations: [origin, destinationPlace],
    useEntryPoints: 'main-when-available'
});

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

A parameter the endpoint cannot accept

calculateRoute() and calculateReachableRange() call two endpoints that do not accept the same parameters. The SDK never drops one silently. It either:

A request that dropped an input would still return a route with plausible numbers, computed from something other than what you asked for.

API reference

Related guides and examples

Related guides

Related examples