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:

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

const routes = await calculateRoute({
    locations: [
        [4.897070, 52.377956],  // Amsterdam
        [4.288788, 52.078663],  // The Hague
        [4.462456, 51.926517]   // Rotterdam
    ]
});

GeoJSON points and features

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

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

const waypoints = await Promise.all([
    geocodeOne('Amsterdam, Netherlands'),
    geocodeOne('The Hague, Netherlands'),
    geocodeOne('Rotterdam, Netherlands')
]);

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:

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

const routes = await calculateRoute({
    locations: [
        [4.9, 52.3],  // Origin waypoint
        [
            [4.85, 52.25],  // Path points
            [4.80, 52.20],
            [4.75, 52.15]
        ],
        [4.5, 51.9]   // Destination waypoint
    ]
});

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

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

const routes = await calculateRoute({
    locations: [
        [4.8970, 52.3779], // Amsterdam
        utrechtToRotterdam.features[0],
        [2.3522, 48.8566]  // Paris
    ]
});

Displaying waypoints on map

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

await routingModule.showRoutes(routes);
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

Related guides and examples

Related guides

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

Related examples

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