Locations

locations is the ordered list a route passes through. Each entry is one of two kinds:

A waypoint is a single point the route stops at. Every waypoint ends a leg, with an arrival instruction. There is no “pass-through” waypoint.
A path is a sequence of points the route must follow, for route reconstruction.

A request needs at least two waypoints, or one path on its own.

A route takes at most 150 waypoints.

In the demo below, pick a list of waypoints, with or without an origin or a destination, and see the pin each position gets.

Single point waypoints

Coordinate pairs

Pass [longitude, latitude] pairs:

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

3
const routes = 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

A GeoJSON Point, or any Feature<Point>, is a waypoint too, so you can pass geocoding and search results unchanged:

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 routes = await calculateRoute({ locations: waypoints });

A place with entry points is routed to its geometry, unless you set useEntryPoints: 'main-when-available', which routes to its main entrance instead, or to the first untyped entry point a reverse geocoded place carries (Entry points).
A waypoint feature’s properties carry its per-stop options (the wait there, the arriving leg’s cost model, candidate entrances). Per-stop options lists them.

Path arrays

A path forces the route along given coordinates. Its first and last points become stops as well, so it shapes the route without removing a leg:

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

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

A route feature from an earlier call is a path as well, and keeps its leg boundaries as stops:

1
const utrechtToRotterdam = await calculateRoute({
2
    locations: [[5.1230, 52.0919], [4.4624, 51.9265]]
3
});
4

5
const routes = await calculateRoute({
6
    locations: [
7
        [4.8970, 52.3779], // Amsterdam
8
        utrechtToRotterdam.features[0],
9
        [2.3522, 48.8566]  // Paris
10
    ]
11
});

Displaying waypoints on map

RoutingModule.showWaypoints takes the same waypoints, but not paths. clearWaypoints removes the pins:

1
await routingModule.showRoutes(routes);
2
await routingModule.showWaypoints(waypoints);

Waypoints in the routing module guide covers the pins, their labels and their events. To insert a stop at the best position in an existing list, use a core route utility.

API reference

CalculateRouteParams – Route calculation parameters
RoutePlanningLocation – Every accepted location type
Waypoint – Waypoint feature type

Route planning parameters – Every other option
Geocoding – Addresses to waypoints
Search – Places to route to
Displaying routes – Routes and waypoints on the map

Waypoints – Multi-stop routes and waypoint management
Map route reconstruction playground – A drawn path as a route location