Formatting

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.features[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.features[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.