Demografia explorer

demografia-explorer

demo.istat.it non è SDMX: è un'applicazione a form, di cui la CLI opendemografia replica ogni <form> come comando. Tutti i comandi accettano -o table|json|csv; per il parsing usa -o json | jq. Exit 2 = errore o nessun match, 0 = ok.

Regola prima di tutte le altre: lo schema non è nella CLI, è nella pagina della tavola. Non indovinare i nomi dei parametri — chiedili a info, che li legge dal vivo. Cambiano da query a query (a contro anno, cittadinanza contro nascita) e a volte lo stesso nome significa un'altra cosa (in PPC il parametro ripartizione è etichettato "Provincia").

Fase 0 — Prima di tutto: il dato esiste?

Spesso la domanda vera non è "dammi i numeri" ma "questo dato esiste, e a che dettaglio?". which risponde a quella, e la descrizione che restituisce dice granularità e copertura temporale.

opendemografia -o json which "origine prevalente degli stranieri in un comune"
# → RCS · "Popolazione residente al 1° gennaio per sesso, comune e singola
#          cittadinanza o paese di nascita dal 2002"

Se which esce con 2, nessuna tavola corrisponde: mostra opendemografia list invece di insistere con sinonimi.

Fase 1 — Scegli la tavola

opendemografia list                              # tutto
opendemografia list --kind app                   # solo le tavole interrogabili
opendemografia list --section "Decessi"          # per sezione tematica

Due tipi di voce:

• app — tavola interattiva, si interroga con get.
• file — sotto-sito a soli download (tavole/?t=). Niente query: files / download. Qui stanno indicatori demografici, trasferimenti di residenza, serie mensili di nascite e decessi, separazioni e divorzi, permessi 1992-2010, ricostruzione 1982-1991: dati che nelle tavole interrogabili non esistono affatto.

CDQ compare nel catalogo ma non è interrogabile da questa CLI.

Fase 2 — Leggi lo schema della query

opendemografia info RCS                  # tutte le query della tavola
opendemografia info RCS --query 0        # una sola
opendemografia -o json info RCS --query 0 | jq '.query[0].parametri[] | {parametro, etichetta, default}'

Ogni tavola ha una o più query, indicizzate da --query N. Per ogni parametro ottieni il dominio completo con le etichette: sono i valori ammessi, non c'è da inventarne altri.

I parametri territoriali regione, provincia, comune compaiono con "dominio": "cascata": il loro elenco non sta nella pagina, si ottiene da territories.

Fase 3 — Territori, se ti serve un codice

opendemografia -o json territories --year 2025 --cat RCS --provincia 058
opendemografia -o json territories --year 2025 --cat RCS --provincia 058 --resolve Velletri

Due avvertenze che fanno fallire le chiamate se ignorate:

• --cat è il valore di hid-cat della tavola (vedi info → campi_fissi), non il codice tavola: FE1 ha hid-cat=FE2.
• la cascata dipende dall'anno, perché riflette i confini amministrativi di quell'anno. Per la storia delle variazioni territoriali l'autorità è opensituas, non questa CLI.

Se conosci già il codice ISTAT del comune puoi saltare questa fase: get ricostruisce da solo la catena ripartizione → regione → provincia (il portale la pretende completa).

Fase 4 — Prendi i dati

opendemografia -o csv get RCS --query 0 --comune 058111 --a 2025
opendemografia -o csv get RCS --query 0 --comune 058111 --a 2025 --out velletri.csv
opendemografia -o json get RCS --query 1 --comune 058111 --a 2025   # per paese di NASCITA

Un parametro sbagliato non produce dati vuoti: produce exit 2 con l'elenco dei parametri o dei valori validi. Leggi il messaggio e correggi, non tentare varianti a caso.

Per il bulk: scarica, non ciclare

Non fare un ciclo di get sui comuni. Il portale sta sulla stessa infrastruttura ISTAT che blocca gli IP abusivi per uno o due giorni, e 7.900 chiamate sono esattamente il traffico che fa scattare il blocco.

Molte tavole pubblicano l'intero dataset come file già pronto:

opendemografia -o json files RCS --sizes            # cosa c'è, e quanto pesa
opendemografia download RCS --year 2025 --match cittadinanza --out ./dati

Per RCS è un CSV con tutti i comuni per tutte le cittadinanze: una richiesta invece di 7.900. PPC ha un file per regione, D7B uno per anno; FE1 non ne ha, e lì l'unica via è get.

I due percorsi non restituiscono lo stesso oggetto:

	get	download
formato	JSON/CSV con chiavi italiane (maschi, femmine, totale)	CSV separato da ;
colonne	anno, denominazione, maschi, femmine, totale	Anno;Codice Istat;Denominazione;…;Zona;Continente;…
valori	codificati dal portale, decodificati dalla CLI	già in chiaro

Stessi numeri, schemi diversi: non scrivere codice che li tratta come intercambiabili.

Quando non usare questa CLI

Se il dato è servito bene da SDMX, usa opensdmx: è lo standard aperto e porta metadati propri. La mappa tavola ↔ dataflow sta in docs/sdmx-overlap.md, e si accumula man mano che le tavole vengono verificate.

Il caso in cui questa CLI vince nettamente è RCS: il dataflow SDMX municipale equivalente (29_317_DF_DCIS_POPSTRCIT1_23) risponde HTTP 500 con codici territorio validi, e comunque copre solo gli stranieri e solo la cittadinanza — niente italiani, niente paese di nascita, niente serie dal 2002.

Auto-orientamento

opendemografia agent-context     # schema JSON della CLI, comandi, flag, exit code

Ritmo delle richieste

La CLI ritma già le chiamate (OPENDEMOGRAFIA_DELAY, default 1 s) e mette in cache pagine e cascata per 7 giorni (cache-clear per svuotare). Non parallelizzare, non abbassare il delay.