Collezione di dati e utilities per facilitare il riuso dei dati ISTAT e ANPR sui confini amministrativi italiani (versione generalizzata meno dettagliata).

Per approfondimenti e discussione è aperto un thread dedicato su Forum Italia.

Sito ufficiale: https://www.confini-amministrativi.it.

Nel file sources.json ci sono i link a tutti gli shapefile rilasciati da ISTAT dal 1991 elencati in questa tabella, il link all'archivio storico dei comuni di ANPR e le risorse Linked Open Data del progetto OntoPiA.

Lo schema del file di configurazione è descritto nel file sources.schema.json secondo lo standard JSON Schema. La validità del file viene verifica a runtime prima dell'elaborazione. Per validare il file a mano: bash run.sh validate.

Lo script main.py scarica gli archivi zip dal sito ISTAT, li decomprime e li elabora in cartelle nominate con la data di rilascio: dist/api/v2/it/YYYYMMDD/. Scarica anche il file di ANPR e lo arricchisce con i dati ISTAT contenuti negli shapefile.

Al momento sono supportati i seguenti formati di output:

• ESRI shapefile (ZIP), il formato originario in cui l'ISTAT pubblica i dati ufficiali, ma con le geometrie corrette, la normalizzazione del charset a UTF-8 e la proiezione a EPSG:4326.
• Comma-separated values (CSV) con la tabella dei dati arricchiti dei territori (UTF-8, virgola come separatore, doppie virgolette come delimitatori di stringa, new line come separatore di riga)
• JavaScript Object Notation (JSON) con gli stessi dati del CSV
• GeoJSON con gli stessi dati dello shapefile
• TopoJSON con gli stessi dati dello shapefile
• GeoPackage con gli stessi dati dello shapefile
• GeoParquet con gli stessi dati dello shapefile
• Geobuf con gli stessi dati dello shapefile
• SVG con i contorni in grafica vettoriale dello shapefile (linee nere e bianche, sfondo trasparente)
• PNG con i contorni in grafica raster dello shapefile (linee nere e bianche, sfondo trasparente)
• WEBP con i contorni in grafica raster dello shapefile (linee nere e bianche, sfondo trasparente)
• JPEG con i contorni in grafica raster dello shapefile (linee nere su sfondo bianco e bianche su sfondo nero)

Il file di ANPR è quello originale arricchito delle denominazioni e dell'indicazione degli shapefile in cui i comuni sono presenti.

Avvertenza: nel repository è incluso solo il codice sorgente dell'applicazione e non i file generati.

Nella cartella tutorials/ ci sono alcuni how-to che mostrano come usare le risorse di questo progetto in vari ambiti e con vari software:

• QGIS

Se usi queste risorse, contribuisci anche tu con un tutorial!

La tabella seguente riporta tutte le release disponibili con la rispettiva data di generazione.

L'obiettivo di questo progetto è automatizzare completamente la generazione di risorse geografiche italiane utili in diversi ambiti di mapping e GIS a partire dai dati storici ufficiali rilasciati da ISTAT e ANPR. I task includono il download, l'omogeneizzazione di codifiche e formati, la correzione di errori di geometrie, la generazione di raggruppamenti di territori a tutti i livelli (es. i comuni di una regione), la conversione in diversi formati geografici e la generazione di mappe interattive per una fruizione semplificata di ognuno di essi.

La struttura dell'albero di cartelle di output è conforme allo standard REST delle Web API, per cui il risultato finale è effettivamente una API statica, descritta mediante lo standard OpenAPI.

Tutte le risorse disponibili sono automaticamente raggiungibili grazie alla presenza di file index.json in ogni cartella conformi alla specifica Hypertext Application Language (HAL).

Tutte le cartelle mostrano una preview dei dati geografici che contengono in una mappa interattiva gestita da LeafletJS.

Lo script di generazione è scritto in Python (v3.11) e le sue dipendenze dirette sono elencate nel file requirements.txt.

Oltre a queste si richiede che alcune librerie siano installate nel sistema, in particolare GDAL e SQLite con l'estensione Spatialite.

Per semplificare la portabilità dello script è possibile (e conveniente) eseguirlo in un container Docker, per cui è fornito un Dockerfile con cui fare la build dell'immagine.

Si consiglia caldamente di usare la versione containerizzata con Docker.

Modalità consigliata

Clona questo repository con Git: git clone https://github.com/teamdigitale/confini-amministrativi-istat.git. Entra nella cartella appena creata: cd confini-amministrativi-istat/.

L'utility run.sh contiene degli shortcut per gestire più facilmente l'immagine docker dell'applicazione (in ambiente windows si raccomanda l'uso di Git Bash). Per l'elenco di tutti i comandi supportati: bash run.sh help.

Effettua la build delle immagini: bash run.sh build (usa rebuild per non fare uso della cache).

Esegui il container per ogni tipologia di confine amministrativo e per tutte le versioni con bash run.sh generate oppure indicando la singola versione di interesse con bash run.sh generate YYYYMMDD.

Avvertenza: l'esecuzione può richiedere alcune ore o anche molte nel caso dell'elaborazione di tutte le versioni.

Naviga le API e la loro documentazione eseguendo un web server in locale: bash run.sh serve [PORT], la porta di default è la 8080.

Modalità altamente sconsigliata, le dipendenze indirette sono molte e si reggono su un equilibrio precario tra le versioni di ogni libreria.

Clona questo repository con Git: git clone https://github.com/teamdigitale/confini-amministrativi-istat.git. Entra nella cartella appena creata: cd confini-amministrativi-istat/.

Il file requirements.txt elenca tutte le dipendenze necessarie a eseguire l'applicazione. Si consiglia di operare sempre in un ambiente isolato creando un apposito virtual environment.

Con Poetry è sufficiente entrare nel virtualenv con poetry shell e la prima volta installare le dipendenze con poetry install come descritte nel file pyproject.toml.

Infine, per eseguire l'applicazione ed elaborare tutte le versioni: python main.py. Per specificare una singola versione di interesse: SOURCE_NAME=YYYYMMDD python main.py.

Il file dist/api/v2/openapi.v2.yml contiene le specifiche conformi allo standard OpenAPI v3.1.

Con bash run.sh serve puoi navigare la documentazione in maniera interattiva sia dalla homepage (http://localhost:8080), sia come pagina standalone (http://localhost:8080/api/v2/).

L'homepage del sito offre una preview dei dati su mappa interattiva (solo desktop) e la possibiltà di scaricare la risorsa scelta mediante form. Contiene anche la documentazione completa dell'API e la possibilità di navigarla interattivamente grazie a Swagger UI.

Per il codice sorgente dell'homepage si rimanda al README dedicato.

Con bash run.sh dev YYYYMMDD è possibile eseguire lo script main.py all'interno di un container senza effettuare una nuova build dell'immagine.

Per lo sviluppo dell'homepage si rimanda al README dedicato.

Ogni contributo è benvenuto, puoi aprire una issue oppure proporre una pull request, così come partecipare alla discussione su Forum Italia. Per favore leggi interamente e con attenzione il Codice di Condotta e le Regole di Contribuzione prima di farlo.

Ringraziamo il Team per la Trasformazione Digitale per aver ospitato questo progetto nella sua primissima fase di ideazione e realizzazione.

Un ringraziamento anche a Datafactor Agrigento per il supporto e il prezioso contributo di finalizzazione del file di configurazione sources.json.

Ringraziamo anche Dataninja srl per il lavoro pionieristico sul tema, Density Design che con RAWGraphs ha fatto emergere per la prima volta l'esigenza di un'API di questo tipo e SparkFabrik srl per aver reso possibile la finalizzazione del progetto.

L'uso di questo software è concesso sotto licenza GNU Affero General Public License.