Locations

VERSION 0.41.1 PUBLIC PREVIEW

The locations parameter defines waypoints and paths for route calculation. Routes pass through locations in the specified order, creating a multi-stop journey.

You can provide two types of locations:

Single point waypoints
Path arrays

Note: The origin and destination must be single point waypoints.

Maximum 150 waypoints per route.

Single Point Waypoints

Single point waypoints are considered exact stops along the route. Each creates an additional route leg with arrival instructions.

Coordinate Pairs

Specify locations as [longitude, latitude] coordinate pairs:

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

3
const route = await calculateRoute({
4
    locations: [
5
        [4.897070, 52.377956],  // Amsterdam
6
        [4.288788, 52.078663],  // The Hague
7
        [4.462456, 51.926517]   // Rotterdam
8
    ]
9
});

GeoJSON Points and Features

Any object with coordinates (Point geometry, or Feature) can be passed as a waypoint. This allows you to use responses from our services directly as locations.

Using geocoded locations as waypoints:

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

3
const waypoints = await Promise.all([
4
    geocodeOne('Amsterdam, Netherlands'),
5
    geocodeOne('The Hague, Netherlands'),
6
    geocodeOne('Rotterdam, Netherlands')
7
]);
8

9
const route = await calculateRoute({ locations: waypoints });

Using search results as waypoints:

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

3
const origin = await search({
4
  query: 'Coffee shop',
5
  position: [4.9041, 52.3676], // Amsterdam
6
  limit: 1
7
});
8
const destination = await search({
9
  query: 'Coffee shop',
10
  position: [4.462456, 51.926517], // Rotterdam
11
  limit: 1
12
});
13

14
const route = await calculateRoute({ locations: [
15
    origin.features[0],
16
    destination.features[0],
17
]});

Path Arrays

Path arrays contain coordinate sequences for route reconstruction, forcing the route to follow a specific path.

Provide coordinate sequences for route reconstruction:

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

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

Use another route as a path by extracting its geometry coordinates:

1
const route1 = await calculateRoute({
2
  locations: [
3
    [5.1230, 52.0919],  // Utrecht
4
    [4.4624, 51.9265]   // Rotterdam
5
  ]
6
});
7

8
const route2  = await calculateRoute({
9
  locations: [
10
    [4.8970, 52.3779], // Amsterdam
11
    route1.features[0].geometry.coordinates,
12
    [2.3522, 48.8566]  // Paris
13
  ]
14
});

Displaying Waypoints on Map

Use the showWaypoints method of the Routing Module to display waypoints as markers on the map.

Call showWaypoints after route calculation to visualize waypoints.
Call clearWaypoints to clear waypoints.

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

3
const waypoints = await Promise.all([
4
    geocodeOne('Amsterdam, Netherlands'),
5
    geocodeOne('The Hague, Netherlands'),
6
    geocodeOne('Rotterdam, Netherlands')
7
]);
8

9
const route = await calculateRoute({ locations: waypoints });
10
await routingModule.showRoutes(route); // Display the route line
11
await routingModule.showWaypoints(waypoints); // Display waypoints as markers

API Reference

For detailed type information, see:

CalculateRouteParams - Route calculation parameters
Waypoint - Waypoint feature type

Map Integration

Routing Module - Display multi-stop routes and waypoints on the map with visual markers and route styling
Places Module - Show waypoints as interactive markers with popups and custom styling

Waypoints - Complete multi-stop route example with waypoint visualization and management
Map Route Reconstruction - Interactive route building with custom waypoint placement

Route Planning Parameters - Comprehensive route planning with configuration options
Geocoding - Convert waypoint addresses to coordinates for precise route planning
Search - Find potential waypoints and destinations along your route