Progetti pubblici sotto casa

Guida agli open data

Una guida per chi parte da zero. Ogni esempio è stato eseguito davvero sui dati di Arezzo il giorno in cui è stato scritto questo sito; i numeri che vedi sono quelli reali.

Esempi eseguiti sui dati al 30/06/2026

1. Cosa sono gli open data

Gli open data (dati aperti) sono informazioni pubbliche che chiunque può scaricare, controllare e riusare, in un formato che un computer sa leggere. Un esempio: l'elenco dei progetti finanziati con soldi pubblici, con importi e date. Aperto significa che non serve chiedere il permesso e non si paga.

2. Dove si trovano

Ogni amministrazione pubblica può pubblicarli. Alcuni punti di partenza: dati.gov.it (catalogo nazionale) e OpenCoesione, la fonte di questo sito. OpenCoesione offre due strade: file interi da scaricare (per esempio l'elenco di tutti i progetti, in un archivio compresso) e una API, cioè un servizio per chiedere solo i dati che servono.

3. Licenze

Un dato aperto ha una licenza che dice cosa puoi farne. I dati di OpenCoesione usano la licenza CC BY 4.0 (Creative Commons Attribuzione): puoi copiarli, modificarli e anche usarli commercialmente, a patto di citare la fonte. Per esempio: «Fonte: OpenCoesione, dati al 30/06/2026».

4. Cos'è una API, con un esempio vero

Una API (interfaccia di programmazione) è un indirizzo web che invece di una pagina da leggere restituisce dati. Non serve installare nulla: basta il browser. Apri questo indirizzo:

https://opencoesione.gov.it/it/api/

Apri nel browser

Vedrai un elenco di «sezioni» della banca dati. Questa è la risposta che abbiamo ottenuto:

{
  "progetti": "https://opencoesione.gov.it/it/api/progetti/",
  "soggetti": "https://opencoesione.gov.it/it/api/soggetti/",
  "aggregati": "https://opencoesione.gov.it/it/api/aggregati/",
  "temi": "https://opencoesione.gov.it/it/api/temi/",
  "nature": "https://opencoesione.gov.it/it/api/nature/",
  "territori": "https://opencoesione.gov.it/it/api/territori/",
  "programmi": "https://opencoesione.gov.it/it/api/programmi/",
  "data_aggiornamento": "20260630"
}

Ogni voce è un altro indirizzo. Noi useremo progetti.

5. Leggere il JSON

I dati arrivano in formato JSON: testo con coppie «nome: valore» tra parentesi graffe. Apri l'indirizzo seguente (chiede i progetti del Comune di Arezzo, due soltanto):

https://opencoesione.gov.it/it/api/progetti/?format=json&territorio=arezzo-comune&page_size=2

Apri nel browser

Il numero count è il totale dei progetti trovati: 12590. Il primo risultato, ridotto ai campi principali, è questo:

{
  "cod_locale_progetto": "6TO384848",
  "cup": "I71B02000030019",
  "oc_titolo_progetto": "Variante in riva destra d'Arno - 1? e 2? Lotto - dal 01/01/2007",
  "oc_finanz_tot_pub_netto": "51817680,65",
  "tot_pagamenti": "51817680,65",
  "oc_stato_progetto": "Concluso"
}

Si legge così: oc_finanz_tot_pub_netto è il finanziato, tot_pagamenti è il pagato, oc_stato_progetto è lo stato. Gli importi hanno la virgola come separatore decimale e sono scritti come testo.

6. I parametri: chiedere solo quello che serve

Dopo il punto interrogativo ci sono i parametri, separati da &:

Aggiungendo stato=in_corso il totale diventa 473:

https://opencoesione.gov.it/it/api/progetti/?format=json&territorio=arezzo-comune&stato=in_corso&page_size=1

Apri nel browser

7. La paginazione

Con migliaia di risultati la API li consegna a gruppi, le pagine. Nella risposta trovi current_page (pagina attuale: 1), last_page (ultima: 6295) e next, l'indirizzo della pagina successiva. Per passare alla pagina 2 si aggiunge page=2:

https://opencoesione.gov.it/it/api/progetti/?format=json&territorio=arezzo-comune&page_size=2&page=2

Apri nel browser

Il primo progetto della pagina 2 è «Copertura parziale dei costi sostenuti dalle aziende del s.S.R. Nel 2021 per il personale dipendente impegnato nella gestione dell?emergenza». Per scaricare tutto si continua finché next è vuoto, aspettando un secondo tra una richiesta e l'altra per non appesantire il servizio.

8. Il CSV nel foglio di calcolo

Un CSV è una tabella in un file di testo, con le colonne separate da virgole. Si apre con Excel, LibreOffice o Fogli Google. La API di OpenCoesione risponde solo in JSON, quindi abbiamo convertito noi i progetti di questo sito in un CSV: scarica progetti-arezzo.csv (873 righe). Per i file interi, già in CSV, c'è la pagina dati scaricabili di OpenCoesione.

  1. Scarica il file.
  2. In LibreOffice: «File → Apri», scegli il file, nella finestra di importazione lascia «Unicode (UTF-8)» e separatore «Virgola». In Excel: «Dati → Da testo/CSV». In Fogli Google: «File → Importa → Carica».
  3. Per filtrare: seleziona la riga delle intestazioni e attiva il filtro automatico (menu «Dati»). Scegli per esempio stato uguale a «In corso».
  4. Per sommare: seleziona la colonna finanziato_euro e leggi la somma in basso. Fai la stessa cosa con pagato_euro: sono due totali diversi.

9. Importo finanziato e pagamenti

Il finanziato è la somma assegnata al progetto; il pagato è quanto è stato effettivamente versato. Nel progetto «Variante in riva destra d'Arno - 1? e 2? Lotto - dal 01/01/2007» (CUP I71B02000030019) il finanziato è 51.817.681 € e il pagato è 51.817.681 €. In altri progetti le due cifre differiscono: per questo sul sito non vengono mai sommate né confuse.

Cercare un CUP

Il CUP (Codice Unico di Progetto) è il «codice fiscale» di un progetto pubblico: identifica lo stesso progetto in banche dati diverse. Ogni scheda di questo sito lo riporta, e nella tabella di Dati completi puoi scrivere un CUP nel campo «Cerca».

10. Come verificare un dato

  1. Apri la scheda del progetto su questo sito.
  2. Premi «Scheda ufficiale su OpenCoesione» e confronta importi e stato.
  3. Premi «Vedi da dove vengono questi dati»: è il JSON della API. Cerca oc_finanz_tot_pub_netto e tot_pagamenti.

Dettaglio di un progetto, ridotto ai campi principali (https://opencoesione.gov.it/it/api/progetti/6to384848/?format=json):

{
  "cod_locale_progetto": "6TO384848",
  "cup": "I71B02000030019",
  "oc_titolo_progetto": "Variante in riva destra d'Arno - 1? e 2? Lotto - dal 01/01/2007",
  "oc_finanz_tot_pub_netto": "51817680,65",
  "tot_pagamenti": "51817680,65",
  "oc_stato_progetto": "Concluso",
  "oc_data_inizio_progetto": "20090115",
  "oc_data_fine_progetto_effettiva": "20220629"
}

Le date sono scritte come anno, mese, giorno senza separatori: 20220629 significa 29/06/2022.

11. Primi passi con Python (facoltativo)

Se vuoi automatizzare, ecco un programma di poche righe che usa solo la libreria standard di Python (si installa da python.org). Salvalo come progetti.py ed eseguilo con python progetti.py:

import json, urllib.request

url = "https://opencoesione.gov.it/it/api/progetti/?format=json&territorio=arezzo-comune&page_size=2"
with urllib.request.urlopen(url) as risposta:
    dati = json.load(risposta)

print("Progetti trovati:", dati["count"])
for p in dati["results"]:
    print(p["cup"], p["oc_stato_progetto"], p["oc_finanz_tot_pub_netto"], p["tot_pagamenti"])

Risultato ottenuto eseguendolo:

Progetti trovati: 12590
I71B02000030019 Concluso 51817680,65 51817680,65
I11B24000050006 In corso 21000000,00 4630117,59

Quando scarichi molte pagine, aspetta almeno un secondo tra una richiesta e l'altra e salva le risposte sul tuo computer per non ripeterle.