situas-explorer
La CLI opensituas espone le API SITUAS in modo orchestrabile. Tutti i comandi
accettano --output table|json|csv (-o); per il parsing usa -o json | jq.
Due famiglie di interrogazioni:
- Catalogo report — tabelle a una data (snapshot) o su intervallo.
- Query territoriali — storia delle variazioni e ricerca codici di una singola unità.
Fase 1 — Trova il report giusto nel catalogo
Più report condividono lo stesso titolo, distinti solo dal periodo di validità:
guarda sempre la colonna validità prima di scegliere il pfun.
opensituas -o json catalog "comuni" | jq -r '.[] | "\(.pfun) \(.validità) \(.titolo)"'
opensituas -o json catalog --ambito "Unità statistiche"
Campi chiave per voce: pfun (id report), validità, analisi (DATA = data singola,
PERIODO = intervallo), parametri (pfun - pdata oppure pfun - pdatada - pdataa).
Fase 2 — Capisci le colonne
# elenco nomi
opensituas -o json info 50 | jq '[.colonne[].colonna]'
# tabella nome / tipo / descrizione
opensituas -o json info 50 | jq '.colonne[] | {colonna, tipo, guida}'
# vista sintetica per orientarsi rapidamente
opensituas info 50
Fase 3 — Scarica i dati
Per i report DATA (snapshot a una data), senza --date ottieni il dato più
recente: la CLI usa la fine validità mostrata in catalog. Per una data storica
passa --date. (Nota: i link del catalogo portano la data di inizio validità; la CLI la
sostituisce di default con la fine, altrimenti otterresti lo snapshot più vecchio.)
opensituas -o json get 61 # comuni di OGGI (fine validità)
opensituas -o json get 61 --date 01/01/2000 # report DATA storico: --date DD/MM/YYYY
opensituas -o json count 98 --from 17/03/1861 --to 31/05/2026 # report PERIODO
opensituas -o csv get 61 --out comuni.csv # salva su file
Se la data è fuori dalla finestra di validità, il comando esce con codice 2 e messaggio
REPORT NON DISPONIBILE: scegli una data dentro il periodo mostrato in catalog.
Query territoriali
Storia delle variazioni di un'unità (storia_ua / variazioni)
opensituas -o json storia comune Roma
opensituas -o json storia comune 058091 --dettaglio # + provvedimento e unità coinvolte
opensituas -o json storia regione Lazio # unisce le forme storiche (es. Compartimento→Regione)
opensituas -o json storia provincia 058 # usa il codice se il nome è ambiguo
Tipi: comune, provincia (uts), regione. Se il nome è ambiguo (più unità con codici
diversi) il comando lo segnala con i candidati: rilancia con il codice preciso.
Ricerca codice Istat
opensituas -o json cerca-codice comune Roma # codici, denominazioni, validità
Casi d'uso tipici
Master table codici — join universale con altri dataset
Il report 61 è la riga-per-comune con tutti i livelli gerarchici. Chiave universale:
PRO_COM_T (6 caratteri alfanumerici). Usarlo come base per qualsiasi join su dati
pubblici italiani (ISTAT, Ministeri, Open Data PA).
opensituas -o csv get 61 --out comuni.csv
opensituas -o json get 61 | jq '.[] | {PRO_COM_T, COMUNE, COD_REG, COD_UTS}'
Codici geografici e statistici ufficiali (e loro storia)
Il SITUAS è la fonte autoritativa dei codici Istat: ripartizioni, regioni, province/uts, comuni — dall'Unità d'Italia a oggi.
Elenco codici e denominazioni a una data:
# Report corrente (1948 → oggi): codici di regioni, province, comuni in un'unica tabella
opensituas -o json get 61 # snapshot alla data più recente
opensituas -o json get 61 --date 01/01/2000 # snapshot storico
# Periodi storici precedenti al 1948
opensituas -o json get 50 # 1927–1947
opensituas -o json get 51 # 1861–1927
Il report 61 (Elenco dei codici e delle denominazioni delle unità territoriali) è il
riferimento principale: contiene codici alfanumerici e numerici di ripartizione, regione,
provincia/uts e comune con tutte le denominazioni ufficiali.
Storia di una singola unità:
opensituas -o json storia comune "Sesto San Giovanni"
opensituas -o json storia comune 015209 --dettaglio # + provvedimento e unità coinvolte
opensituas -o json storia provincia "Milano"
Variazioni in un intervallo (bulk):
# Tutti i comuni con cambio denominazione dal 1861 a oggi
opensituas -o json get 104 --from 17/03/1861 --to 31/05/2026
# Variazioni amministrative e territoriali dei comuni dal 1991
opensituas -o json get 129
Dati di normalizzazione per comune
Per arricchire dataset con attributi demografici e territoriali ufficiali. SITUAS fornisce popolazione, superficie in km² e caratteristiche territoriali per comune.
Popolazione e superficie (dato censuario):
# pfun 74 — Comuni - Dimensione
# Campi chiave: PRO_COM_T, COMUNE, POP_LEG, ANNO_CENSIMENTO, POP_RES, ANNO_POP_RES, AREA_KMQ, ANNO_AREA
opensituas -o csv get 74 --out comuni_dim.csv
| Campo | Contenuto | Disponibile da |
|---|---|---|
POP_LEG |
Popolazione legale (censimento) | IX Censimento 1951 |
POP_RES |
Popolazione residente | 31/12/2001 |
AREA_KMQ |
Superficie territoriale in km² | XIV Censimento 2001 |
ANNO_CENSIMENTO / ANNO_AREA |
Anno di riferimento del dato | — |
Caratteristiche del territorio:
# pfun 73 — Comuni - Caratteristiche del territorio
# Campi chiave: COM_LIT (litoraneo), COM_ISO (isolano), ZONA_ALT (zona altimetrica)
opensituas -o csv get 73 --out comuni_caratteristiche.csv
ZONA_ALT: 1=Montagna interna, 2=Montagna litoranea, 3=Collina interna,
4=Collina litoranea, 5=Pianura.
Join tipico su codice comune:
# Unisci i due report via PRO_COM_T (codice alfanumerico a 6 caratteri)
opensituas -o csv get 74 --out comuni_pop.csv
opensituas -o csv get 73 --out comuni_car.csv
duckdb -c "SELECT p.*, c.COM_LIT, c.COM_ISO, c.ZONA_ALT
FROM read_csv('comuni_pop.csv') p
JOIN read_csv('comuni_car.csv') c USING (PRO_COM_T)"
Aree interne e zone di svantaggio — analisi del divario territoriale
pfun 75 (Comuni - Aree di policy, dal 2014): associa ogni comune alle principali
classificazioni di policy del territorio italiano.
opensituas -o csv get 75 --out comuni_policy.csv
# Filtra solo comuni ultraperiferici:
opensituas -o json get 75 | jq '[.[] | select(.AREE_INT_2020 == "F")]'
# Conta comuni per classe aree interne:
opensituas -o json get 75 | jq 'group_by(.AREE_INT_2020) | map({classe: .[0].AREE_INT_2020, n: length})'
Campi chiave:
| Campo | Contenuto |
|---|---|
AREE_INT_2020 |
Solo la lettera: A=Polo · B=Polo intercomunale · C=Cintura · D=Intermedio · E=Periferico · F=Ultraperiferico (la guida del catalogo scrive A-Polo, ma nei dati c'è solo A) |
MACRO_AI_2020 |
I=Aree interne · C=Centri (non interno) |
ZONE_MONTANE_2014 |
1=Ha zone montane nel territorio · 0=No |
ZONE_V_NAT_2020 |
Zone con vincoli naturali (non montane): 1=Sì · 0=No |
ZONE_S_SPECIFICI_2014 |
Zone con vincoli specifici: 1=Sì · 0=No |
Storia delle variazioni — fusioni, rinominazioni, soppressioni
# Storia di un singolo comune con provvedimento normativo:
opensituas -o json storia comune "Ledro" --dettaglio
opensituas -o json storia comune "Sesto San Giovanni"
# Tutte le variazioni dal 1991 (il più ricco: tipo, norma, testo):
opensituas -o csv get 129 --out variazioni_1991.csv
# Comuni nati da fusione nel 2016 (una riga per ogni comune fuso: si contano i nuovi codici):
opensituas -o json get 129 | jq '[.[] | select(.ANNO == "2016" and (.DESC_COD_VARIAZIONE | startswith("CS")) and (.TESTO_PROVVEDIMENTO | ascii_upcase | contains("FUSIONE")))] | map(.PRO_COM_T) | unique | length'
# Cambi denominazione dall'Unità d'Italia:
opensituas -o json get 104 --from 17/03/1861 --to 31/05/2026 | jq '.[].COMUNE'
# Comuni soppressi (non ricostituiti):
opensituas -o json get 128 | jq 'length'
Il report 129 contiene DESC_COD_VARIAZIONE (tipo variazione: CS=Costituzione,
ES=Estinzione, CD=Cambio denominazione, AP=Cambio appartenenza provincia,
AQ/CE=Acquisizione/cessione territorio, AQES=Acquisizione per estinzione,
CECS=Cessione per costituzione nuova unità, RN=Rinumerazione) e TESTO_PROVVEDIMENTO con la
descrizione normativa. Non esiste un codice "fusione": una fusione è una CS del nuovo
comune (con «FUSIONE» nel testo) più una ES per ogni comune soppresso, e il report ha una
riga per ogni coppia nuovo comune/comune fuso. Il numero di righe non è il numero di fusioni.
Traslazione codici tra due date — analisi longitudinale
Indispensabile quando si confrontano dataset di anni diversi: le fusioni rendono i codici incompatibili. Questi report restituiscono la corrispondenza cod_inizio → cod_fine.
# Mapping codici: come erano nel 2001, come sono nel 2024
opensituas -o csv get 99 --from 21/10/2001 --to 31/12/2024 --out mapping_2001_2024.csv
# Affiancamento completo (blank = comune nato o soppresso nel periodo)
opensituas -o csv get 298 --from 01/01/2011 --to 01/01/2021 --out confronto_2011_2021.csv
# Solo i comuni che hanno cambiato codice:
opensituas -o json get 99 --from 01/01/2010 --to 31/12/2024 \
| jq '[.[] | select(.PRO_COM_T_DT_IN != .PRO_COM_T_DT_FI)]'
Sistemi Locali del Lavoro — mercato del lavoro e specializzazione produttiva
I SLL (aggiornati al Censimento 2021) raggruppano comuni per bacino di pendolarismo. Il report 444 è il più ricco per analisi economiche: contiene la specializzazione produttiva.
opensituas -o csv get 408 --out sll_composizione.csv # comuni → SLL (join key: PRO_COM_T)
opensituas -o csv get 444 --out sll_tassonomie.csv # SLL con classe di pop. e specializzazione
# Tutti gli SLL a vocazione turistica:
opensituas -o json get 444 | jq '[.[] | select(.CLASSE_2021_NAME | contains("tur"))]'
# Distribuzione SLL per specializzazione:
opensituas -o json get 444 | jq 'group_by(.GRUPPO_2021_NAME) | map({gruppo: .[0].GRUPPO_2021_NAME, n: length})'
| Campo pfun 444 | Contenuto |
|---|---|
CL_DIM |
Classe dimensionale per popolazione |
CLASSE_2021_NAME |
Specializzazione produttiva (es. "Manifattura leggera") |
GRUPPO_2021_NAME |
Raggruppamento di specializzazione |
Cities, FUA e NUTS — classificazioni geografiche europee
Per analisi comparate con EUROSTAT. Tre livelli: City (nucleo urbano), FUA (area funzionale), NUTS3 (provincia con classificazioni standardizzate).
opensituas -o csv get 414 --out cities_2021.csv # comuni nelle "Cities" EUROSTAT 2021
opensituas -o csv get 446 --out fua_2021.csv # comuni nelle Zone Urbane Funzionali
opensituas -o csv get 449 --out nuts3.csv # dimensione + urban/rural + costiero + confine
# Quali province sono classificate come "urbane" in Europa?
opensituas -o json get 449 | jq '[.[] | select(.COD_URBAN_RURAL == "1") | .DEN_NUTS3]'
# Province di confine:
opensituas -o json get 449 | jq '[.[] | select(.COD_BORDER_REGION == "1") | .DEN_NUTS3]'
Il report 449 include per ogni NUTS3: POP_RES, AREA_KMQ, COD_URBAN_RURAL
(1=Prevalentemente urbana · 2=Intermedia · 3=Prevalentemente rurale), COD_COASTAL,
COD_BORDER_REGION.
Note operative
- Exit code
2= errore applicativo SITUAS (messaggio su stderr);0= ok. - Il catalogo è cachato 7 giorni;
opensituas catalog --refreshlo rilegge. ricostruzione-codicidel portale non ha un endpoint proprio: corrisponde ai report di catalogo di tipoPERIODO(usali conget/counte--from/--to).