Utilities

VERSION 0.41.1 PUBLIC PREVIEW

The Core bundle provides a collection of utility functions that help you work with geographic data, format values for display, and handle common operations across the Maps SDK.

Working with Coordinates

getPosition

Extracts lng-lat coordinates from various input formats into a standard GeoJSON Position array [longitude, latitude].

Supported input formats:

Raw coordinate arrays: [lng, lat]
GeoJSON Point geometries
GeoJSON Point Features (including Places)

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

3
// From coordinate array
4
const pos1 = getPosition([4.9, 52.3]);
5
// Returns: [4.9, 52.3]
6

7
// From Point geometry
8
const pos2 = getPosition({
9
  type: 'Point',
10
  coordinates: [4.9, 52.3]
11
});
12
// Returns: [4.9, 52.3]
13

14
// From a Place Feature
15
const place = await geocode({ key: 'your-api-key', query: 'Amsterdam' });
16
const pos3 = getPosition(place);
17
// Returns: [longitude, latitude]
18

19
// From a Place with entry point preference
20
const pos4 = getPosition(place, { useEntryPoint: 'main-when-available' });
21
// Returns entry point coordinates if available, otherwise geometry coordinates

Entry point options:

When working with Places that have entry points (building entrances), you can specify which position to extract:

useEntryPoint: 'main-when-available' – Use the main entry point coordinates if available, otherwise fall back to the geometry coordinates

Returns: Position | null – The coordinates as [longitude, latitude], or null if input is invalid.

Working with Bounding Boxes

bboxFromGeoJSON

Calculates or extracts bounding boxes from GeoJSON objects. The function intelligently handles various GeoJSON types and optimizes performance:

Uses existing bbox properties when available (fastest)
Calculates from geometry coordinates when needed
Aggregates bounding boxes from collections
Optimizes large geometries by sampling points

Key behavior: The function prioritizes existing bbox fields over geometry calculations, which is important for Point features from TomTom services that may have a bbox representing a broader area than just the point location.

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

3
// From a Place with existing bbox
4
const place = await geocode({ key: 'your-api-key', query: 'Amsterdam' });
5
const bbox1 = bboxFromGeoJSON(place);
6
// Returns the bbox that came with the place
7

8
// From a Polygon geometry (calculates bbox)
9
const polygon = {
10
  type: 'Polygon',
11
  coordinates: [[
12
    [4.88, 52.36],
13
    [4.90, 52.36],
14
    [4.90, 52.38],
15
    [4.88, 52.38],
16
    [4.88, 52.36]
17
  ]]
18
};
19
const bbox2 = bboxFromGeoJSON(polygon);
20
// Returns: [4.88, 52.36, 4.90, 52.38]
21

22
// From a FeatureCollection (aggregates all features)
23
const places = await search({ key: 'your-api-key', query: 'coffee' });
24
const bbox3 = bboxFromGeoJSON(places);
25
// Returns bbox encompassing all search results
26

27
// From a LineString (calculates from coordinates)
28
const route = await calculateRoute({
29
  key: 'your-api-key',
30
  locations: [[4.9, 52.3], [4.5, 51.9]]
31
});
32
const bbox4 = bboxFromGeoJSON(route.routes[0].geometry);
33
// Returns bbox containing the entire route
34

35
// From an array of GeoJSON objects
36
const bbox5 = bboxFromGeoJSON([place1, place2, place3]);
37
// Returns bbox encompassing all three places

Returns: [minLng, minLat, maxLng, maxLat] | undefined – The bounding box, or undefined if input is invalid.

polygonFromBBox

Converts a bounding box into a GeoJSON Polygon Feature, useful for visualizing bounding box areas on a map.

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

3
// Create a polygon from a bbox
4
const bbox = [4.88, 52.36, 4.90, 52.38];
5
const polygon = polygonFromBBox(bbox);
6
// Returns a GeoJSON Feature with Polygon geometry
7

8
// Visualize a bbox on a map
9
const places = await search({ key: 'your-api-key', query: 'coffee' });
10
const bbox = bboxFromGeoJSON(places);
11
if (bbox) {
12
  const bboxPolygon = polygonFromBBox(bbox);
13
  map.addSource('bbox-area', {
14
    type: 'geojson',
15
    data: bboxPolygon
16
  });
17
  map.addLayer({
18
    id: 'bbox-outline',
19
    type: 'line',
20
    source: 'bbox-area',
21
    paint: { 'line-color': '#3887be', 'line-width': 2 }
22
  });
23
}

Parameters:

bbox – Bounding box as [west, south, east, north]

Returns: Feature<Polygon> – A GeoJSON Feature with a closed Polygon geometry representing the bbox area.

Formatting Values

formatDuration

Formats a duration in seconds into a human-readable time string with intelligent rounding based on duration length.

Rounding behavior:

Durations under 30 seconds return undefined
30-59 seconds round to “1 min”
Minutes are rounded to nearest minute
Hours are displayed when duration ≥ 1 hour

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

3
formatDuration(0);       // undefined (too short)
4
formatDuration(20);      // undefined (too short)
5
formatDuration(30);      // "1 min"
6
formatDuration(60);      // "1 min"
7
formatDuration(100);     // "2 min"
8
formatDuration(1800);    // "30 min"
9
formatDuration(3599);    // "1 hr 00 min"
10
formatDuration(3660);    // "1 hr 01 min"
11
formatDuration(7200);    // "2 hr 00 min"
12
formatDuration(36120);   // "10 hr 02 min"
13

14
// Custom units
15
formatDuration(3660, { hours: 'h', minutes: 'm' });
16
// Returns: "1 h 01 m"
17

18
// Route travel time
19
const route = await calculateRoute({ /* ... */ });
20
const travelTime = formatDuration(route.routes[0].summary.travelTimeInSeconds);
21
console.log(`Estimated time: ${travelTime}`);
22
// Output: "Estimated time: 2 hr 15 min"

Parameters:

seconds – The duration in seconds
options – Optional custom display units for hours and minutes

Returns: string | undefined – Formatted time string, or undefined if duration is too short.

formatDistance

Formats distance in meters into a human-readable string with appropriate units and precision based on the distance. Supports metric, US imperial, and UK imperial unit systems.

Unit systems:

metric (International System)
- Units: meters (m), kilometers (km)
- Used in most of the world
- Decimal-based, no fractions
imperial_us (United States)
- Units: feet (ft), miles (mi)
- Uses fractions for miles (¼, ½, ¾)
- Feet for short distances (< 0.125 mi)
imperial_uk (United Kingdom)
- Units: yards (yd), miles (mi)
- Uses fractions for miles (¼, ½, ¾)
- Yards for short distances (< 0.125 mi)

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

3
// Metric formatting (default)
4
formatDistance(0);       // "0 m"
5
formatDistance(2);       // "2 m"
6
formatDistance(237);     // "240 m"
7
formatDistance(730);     // "700 m"
8
formatDistance(950);     // "1 km"
9
formatDistance(-999);    // "-1 km"
10
formatDistance(2850);    // "2.9 km"
11
formatDistance(283520);  // "284 km"
12

13
// US Imperial formatting
14
formatDistance(2, { type: 'imperial_us' });
15
// Returns: "7 ft"
16

17
formatDistance(100, { type: 'imperial_us' });
18
// Returns: "330 ft"
19

20
formatDistance(205.95, { type: 'imperial_us' });
21
// Returns: "¼ mi"
22

23
formatDistance(1205.95, { type: 'imperial_us' });
24
// Returns: "¾ mi"
25

26
formatDistance(5309.7, { type: 'imperial_us' });
27
// Returns: "3½ mi"
28

29
formatDistance(-18181.7, { type: 'imperial_us' });
30
// Returns: "-11 mi"
31

32
// UK Imperial formatting
33
formatDistance(2, { type: 'imperial_uk' });
34
// Returns: "2 yd"
35

36
formatDistance(150.88, { type: 'imperial_uk' });
37
// Returns: "170 yd"
38

39
formatDistance(4344.3, { type: 'imperial_uk' });
40
// Returns: "2¾ mi"
41

42
formatDistance(21753.68, { type: 'imperial_uk' });
43
// Returns: "14 mi"
44

45
// Custom unit labels
46
formatDistance(1500, { type: 'metric', kilometers: 'KM' });
47
// Returns: "1.5 KM"
48

49
// Route distance
50
const route = await calculateRoute({ /* ... */ });
51
const distance = formatDistance(route.routes[0].summary.lengthInMeters);
52
console.log(`Total distance: ${distance}`);
53
// Output: "Total distance: 45 km"

Parameters:

meters – The distance in meters
options – Optional display units configuration
- type – Unit system: 'metric', 'imperial_us', or 'imperial_uk'
- meters, kilometers, feet, yards, miles – Custom unit labels

Returns: string – Formatted distance string (empty string if input is null/undefined).

Global Configuration

You can set default display units globally using TomTomConfig:

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

3
TomTomConfig.instance.put({
4
  apiKey: 'YOUR_API_KEY_HERE',
5
  displayUnits: {
6
    distance: {
7
      type: 'imperial_us',
8
      feet: 'ft',
9
      miles: 'mi'
10
    },
11
    time: {
12
      hours: 'hr',
13
      minutes: 'min'
14
    }
15
  }
16
});
17

18
// Now all formatting functions will use these defaults
19
formatDistance(1000);  // Uses imperial_us
20
formatDuration(3600);  // Uses custom time units

Options passed directly to formatting functions will override global configuration.