Cos'è GeoJSON? Formato, tipi di geometria e insidie in produzione

GeoJSON è il formato basato su JSON che ogni mappa web moderna sa leggere. Se hai mai disegnato un poligono su una mappa Leaflet, stilizzato un layer vettoriale in MapLibre o memorizzato un'area di servizio in PostGIS, hai lavorato con GeoJSON, anche se l'estensione del file diceva qualcos'altro.

Questa guida spiega cos'è davvero GeoJSON, cosa significano i suoi tipi di geometria, dove compare nei sistemi reali e quali insidie colpiscono i team quando i file GeoJSON lasciano il laptop di uno sviluppatore e arrivano in produzione.

Cos'è davvero GeoJSON

GeoJSON è un formato aperto per codificare strutture dati geografiche, standardizzato dall'IETF come RFC 7946 nel 2016. È un sottoinsieme stretto di JSON: ogni documento GeoJSON è JSON valido, ma la specifica aggiunge regole su quali chiavi sono ammesse, come è strutturata la geometria e come sono ordinate le coordinate.

Il formato è intenzionalmente piccolo. Ci sono solo nove tipi di oggetto top-level nell'intera specifica, e uno sviluppatore competente può tenerli tutti in testa. Quella piccolezza è il motivo per cui GeoJSON è diventato la lingua franca del web mapping: è facile da leggere, facile da scrivere e facile da validare.

Le coordinate sono sempre scritte come [longitudine, latitudine] (con altitudine opzionale come terzo valore), e il sistema di riferimento è fissato a WGS84, lo stesso datum usato dal GPS del tuo smartphone. Niente negoziazione, niente metadati di proiezione, niente dibattito sull'ordine degli assi. Un datum, un ordinamento, ovunque.

Tipi di geometria

GeoJSON definisce sette tipi di geometria. I primi tre sono le primitive:

• Point: una singola coordinata, usata per pin, indirizzi e singoli sensori
• LineString: una lista ordinata di due o più coordinate, usata per percorsi, strade e fiumi
• Polygon: un anello chiuso di coordinate (primo e ultimo punto identici), usato per edifici, particelle e confini amministrativi

I successivi tre sono semplicemente collezioni di queste primitive:

• MultiPoint: molti punti in una singola geometria, utili per rappresentare una catena di negozi come una singola feature
• MultiLineString: molte LineString, usate per percorsi frammentati o sistemi fluviali
• MultiPolygon: molti poligoni, la scelta giusta per qualsiasi paese con isole (quindi quasi tutti)

Il settimo, GeometryCollection, può contenere un mix di qualsiasi delle precedenti. La specifica lo sconsiglia perché la maggior parte dei consumer lo gestisce male, e quasi mai serve. Se ti viene voglia di usare GeometryCollection, di solito è il segno che il modello vuole essere una FeatureCollection.

Feature e FeatureCollection

Una geometria da sola raramente è utile. Devi sapere cosa rappresenta. È a questo che serve Feature: una Feature incapsula una geometria con un oggetto properties che contiene metadati arbitrari.

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [4.8952, 52.3702]
  },
  "properties": {
    "name": "Amsterdam Centraal",
    "type": "station",
    "platforms": 15
  }
}

Una FeatureCollection è una lista di Feature. Quasi ogni file GeoJSON reale che incontrerai nel mondo è una FeatureCollection, perché i dataset reali contengono molte cose.

La scelta progettuale cruciale è che properties è aperto. La specifica non dice nulla su quali chiavi possa contenere o di che tipo debbano essere i valori. Questa è una feature, non un bug: significa che GeoJSON funziona per arredo urbano, confini elettorali, zone di consegna e tracce AIS di navi senza dover estendere il formato. Significa anche che i consumer devono fare attenzione: se dipendi dal fatto che properties.population esista, validalo tu stesso, perché RFC 7946 non lo farà.

Dove compare GeoJSON

Una volta che inizi a notarlo, GeoJSON è ovunque nello stack geospaziale:

• Librerie di mappe: MapLibre GL, Mapbox GL, Leaflet e OpenLayers consumano tutti GeoJSON nativamente come data source per i layer
• Pipeline di vector tile: tool come Tippecanoe prendono GeoJSON in ingresso e producono set MVT (Mapbox Vector Tile) in uscita
• Specifiche di stile: la Mapbox Style Specification, usata da MapLibre, fa riferimento a GeoJSON come tipo di sorgente di prima classe
• Database spaziali: PostGIS, BigQuery GIS e Snowflake importano ed esportano tutti GeoJSON tramite funzioni dedicate
• Output di API: la maggior parte delle moderne API di geocoding, isochrone e routing restituisce Feature GeoJSON come risultati, così la risposta può essere caricata direttamente su una mappa
• Polyline di percorsi: le risposte di navigazione includono comunemente una geometria LineString per il percorso, pronta da renderizzare
• Condivisione di dati: portali open data, export di OpenStreetMap e rilasci di confini amministrativi governativi usano GeoJSON come default quando il pubblico è web

Se un tool sa parlare un qualsiasi formato geospaziale, quasi certamente parla anche GeoJSON.

Insidie in produzione

GeoJSON è indulgente al primo giorno e impietoso al novantesimo. Le trappole che colpiscono i team:

Longitudine prima. RFC 7946 fissa l'ordine come [lon, lat]. Gli umani, gli indirizzi e gran parte della documentazione scrivono lat, lon. Scambiarli è il bug GeoJSON più comune, e il tuo punto finisce nell'oceano sbagliato.

Winding order dei poligoni. RFC 7946 specifica che gli anelli esterni devono essere antiorari e quelli interni (i buchi) orari. Molti file GeoJSON più vecchi ignorano questa regola. Alcuni renderer non se ne curano, altri (in particolare Mapbox GL con poligoni che attraversano l'antimeridiano) renderizzano il poligono come l'inverso di quello che volevi: una piccola isola diventa un buco nell'oceano che copre il resto del mondo.

Gestione dell'antimeridiano. Le geometrie che attraversano il meridiano 180/-180 vanno splittate come da specifica. Poligoni ingenui disegnati attraverso il Pacifico vengono renderizzati come una sottile striscia che gira attorno al pianeta dalla parte lunga.

Niente supporto CRS nativo oltre WGS84. RFC 7946 ha rimosso deliberatamente il vecchio membro crs. Se i tuoi dati sono in una griglia nazionale (British National Grid, RD New, EPSG:3857), devi riproiettare a WGS84 prima di serializzare. I tool che emettono GeoJSON non WGS84 sono tecnicamente non conformi.

Dimensione del file. Una FeatureCollection con milioni di poligoni dettagliati può gonfiarsi fino a gigabyte. Per la consegna nel browser, passa ai vector tile, semplifica la geometria con Douglas-Peucker o fai streaming con GeoJSON newline-delimited (.ndjson).

Validazione. Usa un linter come GeoJSONLint o la libreria geojson-validation in CI. Catturare un winding order invalido o coordinate scambiate al build time è più economico che catturarli da un ticket di un cliente.

GeoJSON in MapAtlas

GeoJSON è il formato di scambio dati di default in tutta la piattaforma MapAtlas. Il prodotto Dynamic Maps accetta sorgenti GeoJSON direttamente per overlay personalizzati, styling e layer interattivi, senza preprocessing richiesto.

La Geocoding API restituisce gli indirizzi matchati come Feature GeoJSON, così un risultato di forward geocode può essere caricato direttamente su una mappa o memorizzato in PostGIS senza rimappare campi. La Isochrone API restituisce le aree di tempo di percorrenza come poligoni GeoJSON, il che significa che una query "luoghi raggiungibili in 15 minuti" è a un fetch e una chiamata addSource di distanza dall'apparire sullo schermo.

GeoJSON non è glamour. È un sottoinsieme piccolo e opinato di JSON con un ordine di coordinate fisso e una manciata di tipi di geometria. Ma è il formato che permette a ogni strato di un moderno location stack, dal database spaziale al canvas della mappa, di concordare su cosa sia un luogo. Metti l'ordine di longitudine giusto, valida il winding e il resto dello stack tende a sistemarsi da solo.