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

Route planning parameters

Every option calculateRoute takes beside its locations. Each is optional, and the defaults below are what an unset option means.

Locations

locations is the one 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); avoidance is not guaranteed when no other route exists:

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, engine, consumption, charge 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. Unset requests every type; a list narrows the response to it, 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
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 plus the wait once there, so inserting an earlier stop leaves them 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, one number for the whole stop — the wait, charging the service planned on an EV route, or both. Leg travel times are driving only, while the route's 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, 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() covers two endpoints — a plain route and the long-distance EV route — and calculateReachableRange() a third. They do not all accept the same parameters, and 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