Routes

Working with Routes

findBestWaypointInsertionIndex

Finds the optimal index to insert a new waypoint into an existing route. The algorithm projects each waypoint onto the route line to determine where the new waypoint fits most naturally along the route’s progression.

1
import { findBestWaypointInsertionIndex } from '@tomtom-org/maps-sdk/core';
2

3
const route = await calculateRoute({
4
  key: 'your-api-key',
5
  locations: [[4.9, 52.3], [5.0, 52.4]]
6
});
7

8
const waypoints = [
9
  [4.9, 52.3],  // origin
10
  [5.0, 52.4]   // destination
11
];
12

13
const newWaypoint = [4.95, 52.35];
14

15
const insertIndex = findBestWaypointInsertionIndex(
16
  route.features[0],
17
  waypoints,
18
  newWaypoint
19
);
20
// Returns: 1 (insert between origin and destination)
21

22
const updatedWaypoints = [
23
  ...waypoints.slice(0, insertIndex),
24
  newWaypoint,
25
  ...waypoints.slice(insertIndex)
26
];
27
// Result: [[4.9, 52.3], [4.95, 52.35], [5.0, 52.4]]

Parameters:

• route – The existing calculated route Feature with LineString geometry
• existingWaypoints – Array of existing waypoints in order (origin, intermediates, destination)
• newWaypoint – The new waypoint to insert

Returns: number – The index where the new waypoint should be inserted. 0 means insert at the beginning; existingWaypoints.length means append at the end. Returns 0 if the route has no coordinates or there are fewer than 2 existing waypoints.

withInsertedWaypoint

Convenience function that combines finding the best insertion index and inserting the waypoint in one step. Returns a new array without modifying the original.

1
import { withInsertedWaypoint } from '@tomtom-org/maps-sdk/core';
2

3
const route = await calculateRoute({
4
  key: 'your-api-key',
5
  locations: [[4.9, 52.3], [5.0, 52.4]]
6
});
7

8
const waypoints = [
9
  [4.9, 52.3],  // origin
10
  [5.0, 52.4]   // destination
11
];
12

13
const newWaypoint = [4.95, 52.35];
14

15
const updatedWaypoints = withInsertedWaypoint(route.features[0], waypoints, newWaypoint);
16
// Returns: [[4.9, 52.3], [4.95, 52.35], [5.0, 52.4]]
17

18
// Recalculate route with the updated waypoints
19
const updatedRoute = await calculateRoute({
20
  key: 'your-api-key',
21
  locations: updatedWaypoints
22
});

Parameters:

• route – The existing calculated route Feature with LineString geometry
• existingWaypoints – Array of existing waypoints in order (origin, intermediates, destination)
• newWaypoint – The new waypoint to insert

Returns: WaypointLike[] – A new array with the waypoint inserted at the optimal position.

getSectionBBox

Calculates a bounding box for a specific section of a route. The function samples three key points along the section — start, midpoint, and end — for an efficient yet accurate result.

1
import { getSectionBBox } from '@tomtom-org/maps-sdk/core';
2

3
const route = await calculateRoute({
4
  key: 'your-api-key',
5
  locations: [[4.9, 52.3], [5.1, 52.5]]
6
});
7

8
const routeFeature = route.features[0];
9
const countrySections = routeFeature.properties.sections.countries;
10

11
for (const section of countrySections) {
12
  const bbox = getSectionBBox(routeFeature, section);
13

14
  if (bbox) {
15
    // Fit the map to this section
16
    map.fitBounds(bbox, { padding: 40 });
17
  }
18
}

Parameters:

• route – The route containing the section
• section – The section to calculate the bbox for, with startPointIndex and endPointIndex referencing coordinates in the route geometry

Returns: [minLng, minLat, maxLng, maxLat] | undefined – The bounding box, or undefined if the route has no coordinates or the section indices are invalid.

calculateProgressAtRoutePoint

Interpolates the cumulative traveled distance and time at an arbitrary coordinate index along a route. Uses the route’s progress array to linearly interpolate between bracketing entries.

1
import { calculateProgressAtRoutePoint } from '@tomtom-org/maps-sdk/core';
2

3
const route = await calculateRoute({
4
  key: 'your-api-key',
5
  locations: [[4.9, 52.3], [5.1, 52.5]]
6
});
7

8
const routeFeature = route.features[0];
9

10
// Get the cumulative distance and time at coordinate index 10
11
const progress = calculateProgressAtRoutePoint(routeFeature, 10);
12

13
if (progress) {
14
  console.log(`${progress.distanceInMeters} m from start`);
15
  console.log(`${progress.travelTimeInSeconds} s from start`);
16
}

Parameters:

• route – The route whose properties.progress will be used for interpolation
• pathIndex – Zero-based index into the route’s coordinate array

Returns: RouteProgressAtPoint | undefined – Interpolated { distanceInMeters, travelTimeInSeconds }, or undefined if the index is out of range or progress data is missing.

getRouteProgressBetween

Calculates distance and travel time for a segment between two arbitrary coordinate indices on a route.

1
import { getRouteProgressBetween } from '@tomtom-org/maps-sdk/core';
2

3
const routeFeature = route.features[0];
4

5
const segmentProgress = getRouteProgressBetween(routeFeature, 5, 20);
6

7
if (segmentProgress) {
8
  console.log(`Segment starts ${segmentProgress.start.distanceInMeters} m from route origin`);
9
  console.log(`Segment ends   ${segmentProgress.end.distanceInMeters} m from route origin`);
10
  console.log(`Segment length ${segmentProgress.delta.distanceInMeters} m`);
11
  console.log(`Segment takes  ${segmentProgress.delta.travelTimeInSeconds} s`);
12
}

Parameters:

• route – The route whose properties.progress will be used for interpolation
• startPathIndex – Zero-based index of the segment start in the route’s coordinate array
• endPathIndex – Zero-based index of the segment end in the route’s coordinate array

Returns: RouteSegmentProgress | undefined – Object with start, end, and delta progress values, or undefined if either index cannot be interpolated.

getRouteProgressForSection

Convenience wrapper around getRouteProgressBetween that accepts a section object directly, using its startPointIndex and endPointIndex as the segment bounds.

1
import { getRouteProgressForSection } from '@tomtom-org/maps-sdk/core';
2

3
const routeFeature = route.features[0];
4
const trafficSections = routeFeature.properties.sections.traffic ?? [];
5

6
for (const section of trafficSections) {
7
  const progress = getRouteProgressForSection(routeFeature, section);
8

9
  if (progress) {
10
    console.log(`Traffic section starts at ${progress.start.distanceInMeters} m`);
11
    console.log(`Traffic section takes    ${progress.delta.travelTimeInSeconds} s extra`);
12
  }
13
}

Parameters:

• route – The route whose properties.progress will be used for interpolation
• section – A section object with startPointIndex and endPointIndex

Returns: RouteSegmentProgress | undefined – Same as getRouteProgressBetween.

getCoordinateAtRouteProgress

Returns the geographic position and cumulative progress values at the point along a route identified by elapsed time, traveled distance, or an absolute clock time. Accepts a RouteProgressQuery discriminated union — provide exactly one of the three variants.

1
import { getCoordinateAtRouteProgress } from '@tomtom-org/maps-sdk/core';
2

3
const routeFeature = route.features[0];
4

5
// By elapsed travel time
6
const byTime = getCoordinateAtRouteProgress(routeFeature, {
7
  traveledTimeInSeconds: 600
8
});
9

10
// By traveled distance
11
const byDistance = getCoordinateAtRouteProgress(routeFeature, {
12
  traveledDistanceInMeters: 5000
13
});
14

15
// By absolute clock time — elapsed seconds are derived from the route departure time
16
const byClockTime = getCoordinateAtRouteProgress(routeFeature, {
17
  clockTime: new Date('2025-06-01T09:10:00Z')
18
});
19

20
if (byTime) {
21
  const [lng, lat] = byTime.position;
22
  console.log(`Position after 10 min: [${lng}, ${lat}]`);
23
  console.log(`Distance covered: ${byTime.distanceInMeters} m`);
24
}

Values beyond the route’s total range are clamped to the start or end point.

Parameters:

• route – The route to query. Must contain properties.progress data
• query – A RouteProgressQuery — exactly one of:
  • { traveledTimeInSeconds: number } – elapsed seconds from route start
  • { traveledDistanceInMeters: number } – meters traveled from route start
  • { clockTime: Date } – absolute point in time; elapsed seconds are derived using route.properties.summary.departureTime

Returns: RouteCoordinateAtProgress | undefined – Object with position ([longitude, latitude]), travelTimeInSeconds, and distanceInMeters, or undefined if the route has no progress data, the clock time precedes the departure time, or the progress data is incomplete.

getProgressAtNearestRoutePoint

Snaps an arbitrary geographic point to the nearest position on a route and returns the interpolated coordinate and cumulative progress values at that snapped position. Useful for showing progress info when the user hovers or clicks near a route line.

1
import { getProgressAtNearestRoutePoint } from '@tomtom-org/maps-sdk/core';
2

3
const routeFeature = routeResult.features[0];
4

5
// Pass any HasLngLat value — [lng, lat] tuple, { lng, lat } object, a GeoJSON Point, etc.
6
const result = getProgressAtNearestRoutePoint(routeFeature, { lng: 4.92, lat: 52.32 });
7

8
if (result) {
9
  const [lng, lat] = result.position;
10
  console.log(`Snapped to: [${lng}, ${lat}]`);
11
  console.log(`${result.distanceInMeters} m from route start`);
12
  console.log(`${result.travelTimeInSeconds} s travel time from route start`);
13
}

Parameters:

• route – The route to query. Must contain properties.progress data
• point – The reference location to snap to the route. Accepts any HasLngLat value: a [longitude, latitude] tuple, a { lng, lat } object, a GeoJSON Point feature, etc.

Returns: RouteCoordinateAtProgress | undefined – Object with position ([longitude, latitude]), travelTimeInSeconds, and distanceInMeters at the nearest point on the route, or undefined if the route has no progress data, fewer than 2 coordinates, or the progress data is incomplete for the snapped position.