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:

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

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

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
                heightMeters: 2.5,
8
                weightKG: 3500
9
            }
10
        }
11
    }
12
});

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
        roadShieldReferences: 'all'
8
    }
9
});

Route Sections

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

Route section types: carTrain, ferry, tunnel, motorway, pedestrian, toll, tollVignette, country, vehicleRestricted, traffic, carpool, urban, unpaved, lowEmissionZone, speedLimit, roadShields, importantRoadStretch,

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
    computeAdditionalTravelTimeFor: 'all'
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
});

API Reference

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

Related Guides and Examples

Related Guides

• 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

Map Integration

• Routing Module - Display calculated routes on map

Related Services

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