Bounding boxes

A bounding box (BBox) is [minLng, minLat, maxLng, maxLat], or [west, south, east, north]. Padded bounds, a map utility, fits the map to one with padding.

bboxFromGeoJSON

Returns the bounding box of any GeoJSON object, or of an array of them:

• An existing bbox wins. A place covering an area, such as a city or a country, comes with one wider than its point.
• Otherwise, it calculates the box from the geometry. A collection or an array combines its members’ boxes.
• It samples a line or ring with more than 1000 points at intervals, always including its last point.

1
import { bboxFromGeoJSON } from '@tomtom-org/maps-sdk/core';
2
import { calculateRoute, discoverPlaces, geocodeOne } from '@tomtom-org/maps-sdk/services';
3

4
const city = await geocodeOne('Amsterdam');
5
bboxFromGeoJSON(city); // the city's own bbox, not a point
6

7
const cafes = await discoverPlaces({ query: 'coffee', geoBias: { position: [4.9, 52.37] } });
8
bboxFromGeoJSON(cafes); // around every result
9

10
const routes = await calculateRoute({ locations: [[4.9, 52.3], [4.5, 51.9]] });
11
bboxFromGeoJSON(routes.features[0].geometry); // around the path
12

13
bboxFromGeoJSON([city, ...cafes.features]); // around all of them

Returns BBox | undefined: undefined for an input it can’t read.

bboxFromCoordsArray

Returns the bounding box of raw [longitude, latitude] positions, for coordinates you hold before any GeoJSON exists, such as the endpoints of routes not yet calculated. It samples an array of more than 1000 positions the way bboxFromGeoJSON samples a long line:

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

3
bboxFromCoordsArray([[4.9, 52.4], [2.3, 48.8], [13.4, 52.5]]); // [2.3, 48.8, 13.4, 52.5]

Returns BBox | undefined: undefined for an empty or missing array.

bboxFromBBoxes

Returns the bounding box containing all the given ones. It skips undefined entries, so the results of bboxFromGeoJSON combine without checks:

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

3
bboxFromBBoxes([bboxFromGeoJSON(city), bboxFromGeoJSON(cafes)]);

Returns BBox | undefined: undefined for an empty array, or when every entry is undefined.

isBBoxWithArea

Checks whether a bounding box has both a width and a height. A single point, or a line along one meridian or parallel, has a box with no area. Fitting the map to that box zooms in as far as the map goes, so check first and centre on the position instead:

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

3
const bbox = bboxFromGeoJSON(places);
4
if (isBBoxWithArea(bbox)) {
5
    map.mapLibreMap.fitBounds(bbox, { padding: 50 });
6
} else if (bbox) {
7
    map.mapLibreMap.jumpTo({ center: bboxCenter(bbox), zoom: 15 });
8
}

Returns boolean: false also for undefined.

bboxCenter

Returns the [longitude, latitude] centre of a bounding box: the midpoint of its west and east edges, and of its south and north ones. A box whose west edge lies east of its east edge crosses the antimeridian, and its centre does too.

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

3
bboxCenter([4.7, 52.2, 5.1, 52.5]); // [4.9, 52.35]
4
bboxCenter([170, -10, -170, 10]); // [180, 0]

Returns Position.

polygonFromBBox

Turns a bounding box into a GeoJSON Feature<Polygon>, to draw the area on the map:

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

3
const bbox = bboxFromGeoJSON(cafes);
4
if (bbox) {
5
    map.mapLibreMap.addSource('search-area', { type: 'geojson', data: polygonFromBBox(bbox) });
6
    map.mapLibreMap.addLayer({
7
        id: 'search-area-outline',
8
        type: 'line',
9
        source: 'search-area',
10
        paint: { 'line-color': '#3887be', 'line-width': 2 }
11
    });
12
}