Route planning parameters

VERSION 0.53.0 PUBLIC PREVIEW

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:

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

3
const route = await calculateRoute({
4
    locations: [
5
        [4.9041, 52.3676], // Amsterdam coordinates
6
        [2.3522, 48.8566]  // Paris coordinates
7
    ]
8
});

Calculate a route following a specific path using path arrays:

1
const route = await calculateRoute({
2
    locations: [
3
        [4.9, 52.3],  // Origin waypoint
4
        [
5
            [4.85, 52.25],  // Path points
6
            [4.80, 52.20],
7
            [4.75, 52.15]
8
        ],
9
        [4.5, 51.9]   // Destination waypoint
10
    ]
11
});

Calculate a route between two geocoded locations:

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

3
const waypoints = await Promise.all([
4
    geocodeOne('Amsterdam, Netherlands'),
5
    geocodeOne('Paris, France')
6
]);
7

8
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.

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

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

Cost model

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

routeType – Type of route optimization

fast - Optimized by travel time (default)
short - Optimized by travel distance
efficient - Balance between time and fuel/energy consumption
thrilling - Scenic routes with fewer motorways (max 900km)

traffic – What traffic data to consider for route planning

live - Real-time traffic + historical patterns (default)
historical - Typical traffic patterns only

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

tollRoads – roads requiring toll payments
motorways – high-speed limited-access highways (useful for scenic routes or vehicle restrictions)
ferries – water crossings requiring ferry transport
unpavedRoads – unpaved/dirt roads (recommended for standard vehicles)
carpools – carpool/HOV (High Occupancy Vehicle) lanes
alreadyUsedRoads – prevents using the same road segment multiple times (useful for delivery routes)
borderCrossings – crossing international borders (useful for customs/visa considerations)
tunnels – underground tunnels (useful for vehicles carrying hazardous materials)
carTrains – car train transport segments
lowEmissionZones – zones with vehicle emission restrictions

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

Each rectangle is limited to ~160×160 km
Cannot cross the 180th meridian
Latitude must be between −80° and +80°

1
// Fast route considering live traffic
2
const route = await calculateRoute({
3
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
4
    costModel: {
5
        routeType: 'fast', // default
6
        traffic: 'live' // default
7
    }
8
});
9

10
// Short route avoiding tolls
11
const route = await calculateRoute({
12
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
13
    costModel: {
14
        routeType: 'short',
15
        avoid: ['tollRoads']
16
    }
17
});
18

19
// Efficient route avoiding highways and ferries
20
const route = await calculateRoute({
21
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
22
    costModel: {
23
        routeType: 'efficient',
24
        traffic: 'historical',
25
        avoid: ['motorways', 'ferries']
26
    }
27
});
28

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

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.

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

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

Vehicle configuration

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

Configure vehicle-specific routing with the vehicle parameter.

model – vehicle dimensions and engine details

state – current vehicle state (fuel/charge levels)

restrictions – cargo and usage restrictions

preferences – charging preferences (electric vehicles only)

1
// Generic vehicle
2
const route = await calculateRoute({
3
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
4
    vehicle: {
5
        model: {
6
            dimensions: {
7
                weightKG: 3500
8
            }
9
        }
10
    }
11
});

Turn-by-turn guidance

For comprehensive guide on navigation guidance, see Guidance.

Request navigation instructions:

1
const route = await calculateRoute({
2
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
3
    guidance: {
4
        type: 'coded',
5
        version: 2,
6
        phonetics: 'IPA'
7
    }
8
});

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, tollVignette, traffic, tunnel, unpaved, urban, vehicleRestricted, Includes all available section types by default.

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

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.

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

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:

noTrafficTravelTimeInSeconds – Free-flow (no traffic)
historicTrafficTravelTimeInSeconds – Historic traffic patterns
liveTrafficIncidentsTravelTimeInSeconds – Current live traffic

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

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

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.

pauseDurationSeconds – how long the vehicle waits at this stop. Counted into the route’s journey time, not only the arrival time. Not supported on the destination. This one is a standard waypoint property, so RoutingModule.showWaypoints labels the stop’s pin with it.

It comes back on the leg that arrives at the stop, as stopTimeInSeconds:
```
1
const legs = route.features[0].properties.sections.leg;
2
legs[0].summary.stopTimeInSeconds;    // time spent at the first stop
3
legs[0].summary.travelTimeInSeconds;  // driving only, the stop is not in here
```
stopTimeInSeconds is one number for the whole stop, whatever it is spent on — the wait you asked for, charging the service planned on an EV route, or both at one stop. For the breakdown, chargingInformationAtEndOfLeg carries the charging part and whatever is left is waiting.

A leg’s travelTimeInSeconds is driving only, while the route’s total includes every stop — so driving time is the sum of the legs, and the time standing still is the difference.
legCostModel – routeType and avoid for the arriving leg only, falling back to the route-wide cost model. Ignored on the origin, which has no arriving leg.
candidateEntryPoints – approach points to offer the routing engine, with an optional preferredEntryPointIndex. Takes precedence over useEntryPoints for this stop.

1
const route = await calculateRoute({
2
    locations: [
3
        [2.1734, 41.3851],
4
        {
5
            type: 'Feature',
6
            geometry: { type: 'Point', coordinates: [2.4467, 41.5381] },
7
            properties: {
8
                pauseDurationSeconds: 1800,
9
                legCostModel: { routeType: 'short', avoid: ['motorways'] }
10
            }
11
        },
12
        [2.8214, 41.9794]
13
    ]
14
});

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

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

Entry points

Control how building entry points are used:

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

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

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

API reference

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

Route Object - Understanding route structure
Routing Quickstart - Getting started with route calculation
Locations - Specifying route planning locations
Guidance - Navigation instructions
Vehicle Configuration - In-depth vehicle configuration

Route stop wait playground - Adjust the wait at a stop and watch the journey time
Route leg options playground - Give each leg its own route type and avoid list

Map integration

Routing Module - Display calculated routes on map

Geocoding - Convert addresses to coordinates for route planning
Search - Find destinations and points of interest along routes