Il bounding box è la struttura spaziale più semplice e più utile in qualsiasi sistema di mappe. Sono quattro numeri che descrivono un rettangolo in latitudine e longitudine, e li trovi in quasi ogni chiamata API, file GeoJSON e libreria di mappe che userai.
In questa guida vediamo cos'è un bounding box, quali convenzioni di formato devi conoscere, dove si usa in produzione e quali errori colpiscono prima o poi ogni sviluppatore.
La definizione
Un bounding box (bbox) è il più piccolo rettangolo allineato agli assi che contiene un elemento geografico o un insieme di punti. "Allineato agli assi" significa che i lati seguono le linee di latitudine e longitudine: il rettangolo non è ruotato. Lo descrivono quattro numeri: la longitudine a ovest, la latitudine a sud, la longitudine a est e la latitudine a nord.
Per Parigi, il bbox ufficiale del comune è circa [2.224, 48.8156, 2.4699, 48.9022]. Per la Francia metropolitana, Corsica compresa, è circa [-5.142, 41.333, 9.560, 51.089]. Per l'intero pianeta è [-180, -90, 180, 90].
Un bbox è sempre definito da due angoli opposti. Non può descrivere una forma che non sia un rettangolo, ma può descrivere il rettangolo che racchiude qualsiasi forma. Per filtrare dati spaziali in fretta, basta questo.
La questione del formato
Ogni sistema scrive il bbox a modo suo, e questa incoerenza causa la maggior parte dei bug legati ai bbox.
GeoJSON, standard OGC e quasi tutte le API moderne: [west, south, east, north], cioè [minLng, minLat, maxLng, maxLat]. Prima la longitudine, poi la latitudine, entrambe in WGS84.
Leaflet: un oggetto LatLngBounds con gli angoli _southWest e _northEast, prima la latitudine e poi la longitudine. Mapbox GL e MapLibre usano LngLatBounds, con la longitudine prima.
Molte API più vecchie ed export CSV: [south, west, north, east], con la latitudine prima. Leggi la specifica.
Servizi di tile e WMS: il bbox è espresso nelle unità della proiezione (metri Web Mercator, non gradi) quando la tile è in EPSG:3857.
La regola prudente: nel tuo codice non usare mai un array di 4 numeri senza nome. Racchiudilo in un oggetto tipizzato con campi espliciti ({ west, south, east, north }), così l'ordine è chiaro. Converti il formato solo dove parli con un'API esterna.
Dove i bounding box sono indispensabili
Il bbox è il filtro spaziale più veloce che esista. Ecco tre usi classici.
Adattare la mappa a un elemento. Quando l'utente apre un risultato di ricerca, chiami map.fitBounds(bbox) e la mappa cambia zoom e posizione per mostrare l'elemento con il giusto margine. Tutte le librerie di mappe moderne hanno questa funzione.
Filtrare le query API per area. I database e le API di ricerca indicizzano i bbox in modo molto efficiente. Una query come "mostrami tutti i luoghi in quest'area" invia al server il bbox visibile, e il server usa un indice spaziale per restituire solo i record che rientrano. È la base della ricerca sull'area visibile della mappa.
Dare la precedenza a una zona nell'autocompletamento e nella geocodifica. Passa il bbox della mappa che l'utente sta guardando. Il geocoder dà più peso ai risultati al suo interno: se scrivi "Liberty" mentre guardi New York, la Statua della Libertà compare prima di qualsiasi altro Liberty al mondo.
C'è anche un quarto uso, meno evidente: nei sistemi di vector tile il bbox è l'unità di riferimento. Ogni tile copre un bbox noto a un livello di zoom noto, e il renderer le compone nella mappa visibile.
Cosa restituisce un'API
Quasi tutte le API di geocodifica restituiscono un bbox con ogni risultato. Ti dice quanto è grande l'elemento trovato (il bbox di un paese è enorme, quello di un edificio minuscolo) e come adattare la mappa. Una geocodifica di "France" restituisce un bbox su scala nazionale, una di "10 Downing Street" un bbox grande come un edificio.
La dimensione del bbox restituito è anche un controllo veloce sulla precisione. Un risultato con precisione "country" e un bbox grande come un edificio è sospetto. Un risultato con precisione "rooftop" e un bbox grande come una città è sbagliato.
Bounding box che attraversano l'antimeridiano
Un'insidia meno evidente: un bbox che attraversa l'antimeridiano, a 180 gradi (per esempio per la Russia, il Pacifico o le Figi), non si può scrivere con west < east, perché fa il giro del globo. Le convenzioni cambiano da sistema a sistema:
- Alcuni sistemi dividono il bbox in due parti, una per ogni lato dell'antimeridiano.
- Altri accettano
west > easte lo interpretano come "fai il giro". - GeoJSON (RFC 7946) lo consente, con west maggiore di east, mentre le geometrie che attraversano l'antimeridiano vanno tagliate in due.
Per la maggior parte dei progetti europei o su un solo paese il problema non si pone. Se costruisci un prodotto globale (rotte aeree, trasporto marittimo, pesca), verifica esplicitamente il caso dell'antimeridiano.
Bounding box e poligoni
Un bbox è un rettangolo, mentre un elemento reale quasi mai lo è. Il bbox della Francia include parte dell'Oceano Atlantico e della Spagna. Quello di Manhattan include parte del New Jersey e del Queens.
Quando l'approssimazione rettangolare basta (adattare la mappa, un primo filtro veloce), il bbox è lo strumento giusto. Se invece devi sapere se un punto sta davvero dentro l'elemento, ti serve un test point-in-polygon sulla geometria reale del confine. In produzione si fa spesso così: prima filtri per bbox (veloce, indicizzabile, scarta la maggior parte dei record), poi esegui il test point-in-polygon sui record rimasti (più lento ma preciso). La maggior parte dei database spaziali lavora internamente proprio in queste due fasi.
Bounding box nella computer vision
Nel riconoscimento di oggetti, nella robotica o nel rendering 3D potresti trovare l'"oriented bounding box". È un concetto diverso: un OBB è ruotato per aderire alla forma meglio di un rettangolo allineato agli assi. Nei dati geografici lo standard è il bbox allineato agli assi, perché si indicizza bene, si adatta alla griglia delle tile e verificare una sovrapposizione è immediato. I bbox orientati servono per i calcoli con rettangoli ruotati, rari nelle mappe e comuni nella computer vision.
Come MapAtlas usa i bounding box
Ogni risultato della Geocoding API e della Search API contiene un campo bbox con l'estensione dell'elemento trovato, in ordine longitudine/latitudine WGS84: proprio il formato che si aspettano GeoJSON e le librerie di mappe moderne. Con il parametro boundary.rect.* puoi dare la precedenza a un'area visibile nella geocodifica. La Isochrone API restituisce i poligoni dei tempi di percorrenza con un bbox che li racchiude, così puoi adattare la mappa senza calcolarlo tu.
Per un'introduzione pratica a GeoJSON e a come i bbox si inseriscono nel quadro dei dati spaziali, leggi Cos'è GeoJSON e Cos'è un geocode.
Domande frequenti
Cos'è un bounding box?
Un bounding box (spesso abbreviato in bbox) è il più piccolo rettangolo allineato agli assi che contiene un elemento geografico o un insieme di punti. Lo descrivono quattro numeri: longitudine minima e massima, latitudine minima e massima. Nelle mappe i bounding box sono ovunque: servono ad adattare la mappa a un elemento, a filtrare le query su un database per area, a definire l'estensione di una tile e a dare la precedenza ai risultati di geocodifica in una certa zona. Sono la struttura spaziale più semplice e veloce che trovi nel codice di produzione.
Qual è il formato standard di un bounding box?
GeoJSON e quasi tutte le API moderne usano l'ordine [west, south, east, north], cioè [minLng, minLat, maxLng, maxLat]. Usa questo formato come predefinito. Alcune API più vecchie e alcuni export CSV usano [south, west, north, east], con la latitudine prima, e qualcuna usa quattro campi separati. Controlla sempre la documentazione dell'API o del formato. L'errore più comune è invertire latitudine e longitudine: il rettangolo finisce dall'altra parte del pianeta.
Che differenza c'è tra un bounding box e un oriented bounding box?
Un bounding box normale è allineato agli assi: i suoi lati seguono le linee di latitudine e longitudine. Un oriented bounding box (OBB, comune nella computer vision e nei motori di gioco) è ruotato per aderire meglio alla forma. L'area è più piccola, ma i calcoli sono più complessi. Nei dati geografici lo standard è il bbox allineato agli assi, perché si indicizza bene nei database spaziali, si adatta alla griglia delle tile e verificare una sovrapposizione è immediato. I bounding box orientati compaiono nel rendering 3D, nel riconoscimento di oggetti e nei motori fisici.
Come uso un bounding box per filtrare una API di geocodifica?
Passa il bbox come parametro che dà la precedenza all'area visibile. Nella Geocoding API di MapAtlas invii `boundary.rect.min_lon`, `boundary.rect.min_lat`, `boundary.rect.max_lon` e `boundary.rect.max_lat`, e il geocoder mette i risultati dentro quell'area prima di quelli fuori. È fondamentale per l'autocompletamento in una mappa: quando l'utente sposta la mappa, aggiorni il bbox e i suggerimenti seguono quello che sta guardando. Senza questo parametro, cercando 'Springfield' ottieni la Springfield più popolare al mondo, che raramente è quella che l'utente cerca.
