Qualsiasi analisi geografica sull'Italia parte da qui.
Il SITUAS (ISTAT) è la fonte autoritativa dei codici e delle denominazioni ufficiali
di tutte le unità territoriali italiane — dall'Unità d'Italia a oggi. Contiene la
storia di ogni fusione, ridenominazione e soppressione di comuni, province e regioni.
opensituas lo espone come CLI e libreria Python: output table/json/csv
per jq, DuckDB o un agente AI, e DataFrame pandas per analisi e notebook.
opensituas è un'idea di Alice Corona.
- Ottenere i codici Istat ufficiali di tutti i comuni, province e regioni a qualsiasi data — dalla lista corrente allo snapshot storico del 1861.
- Arricchire qualsiasi dataset con popolazione, superficie, zona altimetrica, appartenenza a aree interne, classificazione montagna/collina/pianura.
- Ricostruire la storia di un territorio: quando è nato il comune di Ledro? Quante fusioni ci sono state dal 2010? Quale legge ha cambiato il nome di un comune?
- Confrontare dataset di anni diversi senza inciampare sui codici cambiati: la traslazione codici mappa ogni comune del 2001 nel corrispondente di oggi.
- Trovare il bacino economico di riferimento di un comune tramite i Sistemi Locali del Lavoro (SLL), con la specializzazione produttiva dell'area.
- Usare le classificazioni europee (Cities, FUA, NUTS3) per confronti con dati EUROSTAT: urban/rural, zone costiere, regioni di confine.
Un prompt da copiare e incollare in un agente AI, senza installare prima la skill o configurare altro. L'agente controlla se opensituas c'è, legge l'help, fa una prima interrogazione reale e ti propone come proseguire.
Aiutami a usare opensituas (https://github.com/ondata/opensituas), una CLI Python che interroga il SITUAS dell'ISTAT (https://situas.istat.it/): codici e denominazioni ufficiali di comuni, province e regioni italiane a una data qualsiasi, la storia delle loro variazioni dal 1861 e un catalogo di report con popolazione, superficie e classificazioni territoriali. È in sola lettura.
Procedi così:
1. Controlla se `opensituas --help` funziona. Se manca e l'ambiente lo permette, chiedimi conferma e installalo con `uv tool install opensituas` (oppure `pip install opensituas`).
2. Leggi `opensituas --help`. Per avere comandi, opzioni ed exit code in forma strutturata usa `opensituas agent-context`.
3. Esegui una sola interrogazione di prova e mostrami il risultato reale: `opensituas -o json cerca-codice comune Ledro`
4. Proponimi cosa posso chiedere. Per trovare il report giusto usa `opensituas -o json which "<domanda>"` o `opensituas -o json catalog "<parola>"`, poi `info <pfun>` per le colonne, prima di scaricare dati con `get`.
Regole:
- Usa `-o json` e leggi l'output con jq o con il tuo parser, non la tabella.
- Le date si scrivono GG/MM/AAAA. Per i report di tipo DATA, senza `--date` ottieni il dato più recente; per una data storica controlla prima in `catalog` il periodo di validità del report. Fuori da quel periodo il comando esce con codice 2 e il messaggio REPORT NON DISPONIBILE.
- I codici Istat sono testo: conserva gli zeri iniziali (058091, non 58091).
- Se un nome è ambiguo, il comando elenca i candidati: rilancia con il codice, non sceglierne uno a caso.
- Non dedurre il significato delle colonne dal nome: leggilo con `info`.
- Per il resto segui la documentazione: https://github.com/ondata/opensituas/blob/main/README.md e https://github.com/ondata/opensituas/blob/main/skills/situas-explorer/SKILL.md
Mostrami i comandi usati e i risultati reali, con la fonte (SITUAS, ISTAT), la data di riferimento dei dati e i limiti. Tieni distinti i dati restituiti dal SITUAS dalle tue elaborazioni. Se installazione, rete o esecuzione non sono disponibili, dimmi cosa è bloccato e dammi i comandi documentati da lanciare a mano. Non inventare risultati e non dire di aver eseguito ciò che non hai eseguito. Rispondimi nella mia lingua.
Come CLI, disponibile nel terminale (Python 3.12+):
uv tool install opensituasCome libreria, nelle dipendenze di un progetto Python:
uv add opensituasLa libreria include pandas; non serve un extra separato. L'installazione con
uv tool install è isolata e non rende il modulo importabile dal proprio progetto.
Nota bene: opensituas funziona ancora meglio accoppiato alla skill dedicata per
qualsiasi agente AI che supporti le skill, che guida l'agente nel discovery del catalogo e nei casi d'uso più comuni:
npx skills add ondata/opensituasPer i dettagli sull'installazione della skill vedi docs/skill/README.md.
Le funzioni sono disponibili direttamente da opensituas, senza avviare comandi
shell. Gli esempi seguenti interrogano i servizi ISTAT e richiedono accesso alla
rete (il catalogo dispone anche di cache e snapshot di fallback).
import opensituas
report = opensituas.catalog("comuni", unita="comune")
print(report[["pfun", "titolo"]].head())
print(opensituas.which("popolazione e superficie dei comuni")) # come `opensituas which`
comuni = opensituas.get(61) # snapshot più recente disponibile
comuni_2020 = opensituas.get(61, date="01/01/2020")
print(opensituas.count(61)) # int, senza scaricare il report
print(opensituas.info(61)["colonne"]) # lista di metadati in un dict
storia = opensituas.storia("comune", "Roma", dettaglio=True)
print(storia.attrs["unita"]) # metadati dell'unità selezionata
print(opensituas.cerca_codice("comune", "Roma"))
roma = comuni.loc[comuni["PRO_COM_T"] == "058091"]
roma.to_csv("roma.csv", index=False)I codici restano stringhe, con gli zeri iniziali: 058091 non diventa 58091.
Anche caricando file esterni, specificare il tipo, ad esempio
pd.read_csv("misure.csv", dtype={"PRO_COM_T": str}).
import pandas as pd
# Dati dimostrativi locali, non statistiche ISTAT.
misure = pd.DataFrame({"PRO_COM_T": ["058091"], "valore_demo": [10]})
arricchiti = misure.merge(comuni, on="PRO_COM_T", how="left", validate="many_to_one")Per dati storici scegliere uno snapshot coerente con la data della propria tabella: le fusioni possono cambiare i codici e la composizione dei territori.
| Funzione | Risultato |
|---|---|
catalog(keyword=None, *, ambito=None, unita=None, refresh=False) |
DataFrame del catalogo filtrato |
info(pfun, *, timeout=60.0) |
Dizionario: pfun, report, descrizione, colonne |
get(pfun, *, date=None, date_from=None, date_to=None, timeout=60.0) |
DataFrame dei dati |
count(pfun, *, date=None, date_from=None, date_to=None, timeout=60.0) |
Intero non negativo |
storia(tipo, query, *, dettaglio=False) |
DataFrame degli eventi; attrs["unita"] contiene i metadati |
cerca_codice(tipo, query, *, limit=20) |
DataFrame dei codici o delle voci di disambiguazione |
which(query=None, *, limit=3) |
DataFrame dei report più pertinenti (titolo, unità, colonne) con il comando suggerito; senza query tutto il catalogo |
pfunaccetta interi o stringhe.tipoècomune,provinciaoregione;queryè un nome o codice, da passare come stringa per preservare gli zeri iniziali.- Date
DD/MM/YYYY: per report DATA,get/countsenzadateusano la fine validità; per report PERIODO, usaredate_from/date_to(i valori omessi rimangono quelli nei link del catalogo). Non mescolare i due tipi di filtro. Ad esempio:opensituas.get(99, date_from="21/10/2001", date_to="31/12/2024"). - Nomi delle colonne, ordine e codici testuali restano quelli dei record. Non si convertono automaticamente stringhe in numeri o date e non si riempiono i mancanti.
- Un risultato senza righe è un DataFrame vuoto: il catalogo mantiene le sue colonne note, mentre report e storia senza eventi non ricostruiscono le colonne con richieste extra.
- Con
storia(..., dettaglio=True),provvedimentoeunita_coinvoltesono liste nelle celle; dettagli non disponibili sono liste vuote, come nella CLI. Gliattrsdi pandas non sono garantiti dopo trasformazioni o esportazioni. - Oltre
limitcriteri di ricerca distinti,cerca_codicerestituisce una riga con_ambiguoe fino alimitvociV: non sono risultati completi. Restringere la ricerca usando un codice preciso. timeoutriguarda le richieste publish diinfo/get/count, non il caricamento del catalogo o le query territoriali (default 60 secondi).OPENSITUAS_TIMEOUTrimane un'opzione della CLI, non della libreria.- Gli errori applicativi/API sono eccezioni
SituasError: la libreria non stampa messaggi né termina il processo. Un conteggio vuoto o non valido è un errore, non zero.
try:
dati = opensituas.get(61, timeout=30.0)
except opensituas.SituasError as errore:
print(f"Dati non disponibili: {errore}")# --- catalogo ---
opensituas catalog # tutti i report (pfun, titolo, validità, ...)
opensituas catalog "Comuni" --ambito "Unità amministrative"
opensituas --output json catalog "Ripartizioni" | jq '.[].pfun'
opensituas catalog --refresh # rilegge dal gateway
opensituas info 50 # descrizione + colonne del report 50
opensituas get 61 # report DATA: dato più recente (fine validità)
opensituas get 61 --output csv --out comuni.csv
opensituas count 98 --from 17/03/1861 --to 31/05/2026
opensituas get 61 --date 01/01/2020 # snapshot storico; errore chiaro se fuori validità
# --- query territoriali ---
opensituas storia comune Roma # storia delle variazioni del comune
opensituas storia comune 058091 --dettaglio # + provvedimento e unità coinvolte
opensituas storia regione Lazio
opensituas storia provincia Roma
opensituas cerca-codice comune Roma # codici/denominazioni + validità
# --- per agenti AI ---
opensituas agent-context # JSON versionato: schema CLI (comandi, flag, exit code)
opensituas which "popolazione e superficie dei comuni" # trova report da linguaggio naturale (titolo, unità, colonne)
opensituas which --limit 1 province # max 1 risultato; exit 2 se nessun match
opensituas -o json which "province cessate" | jq '.[].comando_suggerito'Il punto di partenza di qualsiasi analisi che usa dati pubblici italiani. Il report 61 è
una riga per comune con tutti i livelli gerarchici (ripartizione, regione, provincia, comune)
e le denominazioni ufficiali. Chiave di join universale: PRO_COM_T (6 caratteri
alfanumerici, es. 015146).
opensituas -o csv get 61 --out comuni.csv # snapshot corrente
opensituas -o csv get 61 --date 01/01/2000 --out comuni_2000.csvDue report complementari per normalizzare qualsiasi dataset comunale.
opensituas -o csv get 74 --out comuni_dim.csv # POP_LEG, POP_RES, AREA_KMQ, anno riferimento
opensituas -o csv get 73 --out comuni_car.csv # COM_LIT (litoraneo), COM_ISO (isolano), ZONA_ALTZONA_ALT: 1=Montagna interna · 2=Montagna litoranea · 3=Collina interna · 4=Collina
litoranea · 5=Pianura. Join via PRO_COM_T.
Fondamentale per giornalismo sui piccoli comuni, divario territoriale, accesso ai servizi.
opensituas -o csv get 75 --out comuni_policy.csvCampi chiave: AREE_INT_2020 (Polo → Polo intercomunale → Cintura → Intermedio →
Periferico → Ultraperiferico), MACRO_AI_2020 (due classi: interno/non interno),
ZONE_MONTANE_2014, ZONE_V_NAT_2020 (vincoli naturali), ZONE_S_SPECIFICI_2014.
opensituas storia comune "Ledro" --dettaglio # nato da fusione: chi, quando, perché
opensituas storia comune "Sesto San Giovanni"
# Tutte le variazioni dal 1991 a oggi con testo del provvedimento:
opensituas -o csv get 129 --out variazioni_1991.csv
# Solo cambi di denominazione, dall'Unità d'Italia:
opensituas -o json get 104 --from 17/03/1861 --to 31/05/2026 | jq '.[].COMUNE'Il report 129 (Variazioni amministrative e territoriali dal 1991) è il più ricco:
DESC_COD_VARIAZIONE descrive il tipo (fusione, scorporo, cambio nome, cambio codice...),
TESTO_PROVVEDIMENTO riporta la norma di riferimento.
Indispensabile quando si confrontano dataset di anni diversi: le fusioni cambiano i codici.
# Mapping codici comuni: come erano nel 2001, come sono oggi
opensituas -o csv get 99 --from 21/10/2001 --to 31/12/2024 --out mapping_2001_2024.csv
# Affiancamento completo: chi c'era nel 2011 e nel 2021 (con eventuali blank per nuovi/soppressi)
opensituas -o csv get 298 --from 01/01/2011 --to 01/01/2021 --out confronto_2011_2021.csvI SLL raggruppano comuni per bacino di pendolarismo — l'unità di analisi del mercato del lavoro locale. Il report delle tassonomie ha anche la specializzazione produttiva del SLL.
opensituas -o csv get 408 --out sll_composizione.csv # quali comuni appartengono a ogni SLL
opensituas -o csv get 444 --out sll_tassonomie.csv # CL_DIM, CLASSE_2021_NAME, GRUPPO_2021_NAMECLASSE_2021_NAME / GRUPPO_2021_NAME: specializzazione produttiva (es. distretto
manifatturiero, turismo, servizi). Utile per confronti tra aree economicamente simili.
Per analisi comparate con dati EUROSTAT o europei in genere.
opensituas -o csv get 414 --out cities_2021.csv # comuni nelle "Cities" (definizione EUROSTAT)
opensituas -o csv get 446 --out fua_2021.csv # comuni nelle Zone Urbane Funzionali 2021
opensituas -o csv get 449 --out nuts3.csv # POP_RES, AREA_KMQ, urban/rural, costiero, confineIl report 449 (NUTS 3 - Dimensione e classificazioni) include COD_URBAN_RURAL (tipologia
urbano-rurale a livello provinciale), COD_COASTAL e COD_BORDER_REGION — le classificazioni
standardizzate EUROSTAT per i confronti tra paesi.
Il flag globale --output (-o) vale table (default), json o csv. In json/csv
l'output su stdout è pulito (i messaggi diagnostici vanno su stderr), pronto per jq:
opensituas -o json storia comune Roma | jq '.storia[] | {data: ."data evento", evento: .variazione}'
opensituas -o csv get 50 > comuni.csv- Catalogo: ottenuto via gateway POST (
get_elenco_microservizi), cachato in~/.cache/opensituas/catalog.json(TTL 7 giorni), con snapshot incluso come fallback. - Dati report: endpoint pubblici
situas-servizi.istat.it/publish(reportspooljson,reportspooljsoncount,anagrafica_report_metadato_web). Per i reportDATA, senza--datela CLI usa la fine validità (dato più recente); i link del catalogo porterebbero invece la data di inizio (snapshot più vecchio).--date/--from/--tosostituiscono il parametro data. - Query territoriali: servizi
var_get_ua_*(storia) ericercacodice_*via gateway.
Dettagli in docs/architecture.md. Per orchestrazione da agente vedi skills/situas-explorer/SKILL.md.
| Variabile | Default | Descrizione |
|---|---|---|
OPENSITUAS_TIMEOUT |
60 |
Timeout richieste (secondi) |
- opensdmx — Statistiche ufficiali da Eurostat, ISTAT, OCSE e altri provider SDMX, senza allucinazioni.
- ISTAT MCP Server — Dati statistici ISTAT direttamente nel tuo assistente AI, via protocollo MCP.
- CKAN MCP Server — Qualsiasi portale open data CKAN diventa una conversazione in linguaggio naturale.
MIT