Bounding boxes

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

Boxes across the antimeridian

A box whose west edge lies east of its east edge crosses the antimeridian, as RFC 7946 §5.2 has it. Geocoding Fiji, for example, returns [176.84, -21.02, -178.16, -12.46]. The services return that form, and every utility on this page reads and returns it:

• bboxFromCoordsArray, and bboxFromGeoJSON on points, return it when it's the narrower box around the points. Input spanning -180 to 180, such as every country in the world, keeps [-180, …, 180].
• bboxFromGeoJSON reads a line or ring along its edges, which don't wrap: [[179, 0], [181, 0]] gives [179, 0, -179, 0], and [[179, 0], [-179, 0]] runs 358° the other way. Cut a line at 180 to cross, as RFC 7946 asks; the parts merge across the antimeridian.
• bboxFromBBoxes, and bboxFromGeoJSON on several features or parts, return the narrowest box containing every input, across the antimeridian or not.
• polygonFromBBox draws the ring that bboxFromGeoJSON reads back as the same box.

MapLibre's fitBounds and the map's bounds option take a crossing box as it is. Another MapLibre API may need an east past 180. To get one, add 360 to east, as MapLibre's LngLatBounds.adjustAntiMeridian() does.

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

bboxFromCoordsArray([[179.5, -16.8], [-179.8, -16.6]]); // [179.5, -16.8, -179.8, -16.6], 0.7° wide

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.

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

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

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

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

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 reads them as loose points, not a line: for a line or ring, pass a LineString or Polygon to bboxFromGeoJSON. It samples an array of more than 1000 positions the way bboxFromGeoJSON samples a long line:

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

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 narrowest bounding box containing all the given ones. It skips undefined entries, so the results of bboxFromGeoJSON combine without checks:

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

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:

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

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

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.

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

bboxCenter([4.7, 52.2, 5.1, 52.5]); // [4.9, 52.35]
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. For a box across the antimeridian, the ring's east edge is east + 360, so the ring surrounds the box rather than the rest of the world:

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

const bbox = bboxFromGeoJSON(cafes);
if (bbox) {
    map.mapLibreMap.addSource('search-area', { type: 'geojson', data: polygonFromBBox(bbox) });
    map.mapLibreMap.addLayer({
        id: 'search-area-outline',
        type: 'line',
        source: 'search-area',
        paint: { 'line-color': '#3887be', 'line-width': 2 }
    });
}