Source: OpenCoesione · latest data update: 2026-06-30IT
Independent project, for educational purposes, using official data.
Public projects near home

Tutorial: open data

A guide for those starting from zero. Every example was really run on the data of Arezzo; the numbers you see are the real ones. The data fields and project titles are in Italian, as in the source.

Build a basic version of this website, step by step

Examples run on data updated to 2026-06-30

1. What open data are

Open data are public information that anyone can download, check and reuse, in a format a computer can read. An example: the list of projects funded with public money, with amounts and dates. Open means you do not need to ask permission and you do not pay.

2. Where to find them

Every public administration can publish them. Some starting points: dati.gov.it (the Italian national catalogue) and OpenCoesione, the source of this site. OpenCoesione offers two ways: whole files to download (for example the list of all projects, in a compressed archive) and an API, a service to ask only for the data you need.

3. Licences

Open data come with a licence that says what you may do with them. OpenCoesione data use the CC BY 4.0 licence (Creative Commons Attribution): you can copy and modify them, even for commercial use, as long as you credit the source. For example: «Source: OpenCoesione, data updated to 2026-06-30».

4. What an API is, with a real example

An API (application programming interface) is a web address that, instead of a page to read, returns data. You need to install nothing: the browser is enough. Open this address:

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

Open in the browser

You will see a list of «sections» of the database. This is the answer we got:

{
  "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"
}

Each entry is another address. We will use progetti (projects).

5. Reading JSON

Data arrive in JSON format: text with «name: value» pairs between curly brackets. Open the address below (it asks for the projects of the Municipality of Arezzo, only two of them):

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

Open in the browser

The number count is the total of projects found: 12590. The first result, reduced to the main fields, is:

{
  "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"
}

Read it like this: oc_finanz_tot_pub_netto is the funded amount, tot_pagamenti is the paid amount, oc_stato_progetto is the status. Amounts use a comma as decimal separator and are written as text.

6. Parameters: ask only for what you need

After the question mark come the parameters, separated by &:

Adding stato=in_corso the total becomes 473:

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

Open in the browser

7. Pagination

With thousands of results the API delivers them in groups, the pages. In the answer you find current_page (current page: 1), last_page (last: 6295) and next, the address of the next page. To go to page 2 add page=2:

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

Open in the browser

The first project on page 2 is «Copertura parziale dei costi sostenuti dalle aziende del s.S.R. Nel 2021 per il personale dipendente impegnato nella gestione dell?emergenza». To download everything you keep going until next is empty, waiting a second between requests so as not to overload the service.

8. CSV in a spreadsheet

A CSV is a table in a text file, with columns separated by commas. It opens with Excel, LibreOffice or Google Sheets. The OpenCoesione API answers only in JSON, so we converted this site's projects to CSV ourselves: download progetti-arezzo.csv (873 rows; column names and values are in Italian). For the whole files, already in CSV, see the OpenCoesione downloads page.

  1. Download the file.
  2. In LibreOffice: «File → Open», choose the file, in the import window keep «Unicode (UTF-8)» and separator «Comma». In Excel: «Data → From Text/CSV». In Google Sheets: «File → Import → Upload».
  3. To filter: select the header row and turn on the autofilter (the «Data» menu). Choose for example stato equal to «In corso».
  4. To sum: select the finanziato_euro column and read the sum at the bottom. Do the same with pagato_euro: they are two different totals.

9. Funded amount and payments

The funded amount is the sum assigned to the project; the paid amount is what was actually paid out. In the project «Variante in riva destra d'Arno - 1? e 2? Lotto - dal 01/01/2007» (CUP I71B02000030019) the funded amount is €51,817,681 and the paid amount is €51,817,681. In other projects the two figures differ: that is why the site never adds them together or mixes them up.

Looking up a CUP

The CUP (Codice Unico di Progetto, Unique Project Code) is the «tax code» of a public project: it identifies the same project in different databases. Every project page of this site shows it, and in the Full data table you can type a CUP in the «Search» field.

10. How to check a figure

  1. Open the project page on this site.
  2. Press «Official page on OpenCoesione» and compare amounts and status.
  3. Press «See where this data comes from»: it is the API's JSON. Look for oc_finanz_tot_pub_netto and tot_pagamenti.

Detail of one project, reduced to the main fields (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"
}

Dates are written as year, month, day without separators: 20220629 means 2022-06-29.

11. First steps with Python (optional)

If you want to automate, here is a program of a few lines that uses only Python's standard library (install it from python.org). Save it as projects.py and run it with python projects.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 response:
    data = json.load(response)

print("Projects found:", data["count"])
for p in data["results"]:
    print(p["cup"], p["oc_stato_progetto"], p["oc_finanz_tot_pub_netto"], p["tot_pagamenti"])

Result obtained by running it:

Projects found: 12590
I71B02000030019 Concluso 51817680,65 51817680,65
I11B24000050006 In corso 21000000,00 4630117,59

When you download many pages, wait at least a second between requests and save the answers on your computer so as not to repeat them.