Guida all'utilizzo dell'API `get_data` di Italy-Trend

Il servizio get_data di Italy-Trend è un’API gratuita che permette di accedere in modo semplice e immediato ai dati ufficiali del database ISTAT. Grazie a questa API, non è necessario installare pacchetti o librerie specifiche per consultare i dati: basta effettuare una chiamata HTTP e l’API restituirà le informazioni richieste.

L’API get_data facilita anche la gestione di grandi volumi di dati. Poiché molte tabelle ISTAT contengono migliaia di righe, scaricare un’intera tabella in un’unica chiamata può causare timeout o eccessivo trasferimento di dati. Per questo motivo, get_data offre la possibilità di filtrare il contenuto delle tabelle, consentendo di recuperare solo le porzioni di dati realmente necessarie.

Italy-Trend mette a disposizione una pagina chiamata API Builder, un’interfaccia interattiva grazie alla quale è possibile visualizzare l’elenco completo delle tabelle presenti nel database ISTAT, creare le chiavi key per filtrare con precisione i dati desiderati e generare automaticamente snippet di codice Python pronti all’uso per scaricare i dati attraverso il servizio get_data.

Il Database ISTAT

Il database ISTAT, accessibile tramite Italy-Trend, comprende oltre 500 tabelle con un’enorme varietà di informazioni su economia, società e finanza in Italia. Si tratta di un dataset ufficiale, costantemente aggiornato, che copre numerosi ambiti di interesse (dati demografici, produttivi, occupazionali, ecc.). Ogni tabella nel database ha un suo ID univoco che la identifica. Ad esempio:

L’ID "101_1030" si riferisce alla tabella riguardante i Prodotti agroalimentari di qualità DOP/IGP e STG,
L’ID "115_333" si riferisce alla tabella Indice della produzione industriale

Per consultare l’elenco completo delle tabelle e degli ID disponibili, è possibile visitare l'API Builder di Italy Trend.

Struttura tabelle ISTAT

Le tabelle ISTAT seguono una struttura standardizzata che consente di rappresentare i dati in modo chiaro e coerente. Ogni tabella contiene le seguenti colonne principali:

OBS_VALUE: Una colonna numerica che contiene il valore di riferimento del dato della riga della tabella.
TIME_PERIOD: Una colonna che specifica il periodo temporale a cui si riferisce il valore presente in OBS_VALUE.
Uno o più campi aggiuntivi di specificazione o dettaglio del dato, come ad esempio territorio o classe di eta.

La proprietà fondamentale delle tabelle ISTAT è che la chiave primaria della tabella è composta da tutti i campi di specificazione più il campo TIME_PERIOD. Questo schema garantisce l'univocità di ogni riga e consente di filtrare i dati in modo preciso.

Esempio tabella ISTAT


+-------------+---------------+-------------+-----------+
| territorio  | classe di eta | TIME_PERIOD | OBS_VALUE |
+-------------+---------------+-------------+-----------+
| Lombardia   | 18-25         | 2020        | 12345.67  |
| Lombardia   | 18-25         | 2021        | 12500.89  |
| Lazio       | 18-25         | 2020        | 9876.54   |
| Lazio       | 18-25         | 2021        | 10023.11  |
+-------------+---------------+-------------+-----------+

Nell'esempio sopra, le colonne territorio, TIME_PERIOD e classe di eta costituiscono la chiave primaria della tabella. La colonna OBS_VALUE contiene i valori osservabili (ad esempio, popolazione o reddito medio) per ciascun periodo temporale e combinazione di campi di specificazione.

Questo formato consente agli utenti di filtrare i dati utilizzando i campi di specificazione e di analizzare facilmente le informazioni su periodi temporali o categorie specifiche.

Descrizione della funzione `get_data`

get_data è la funzione di Italy-Trend che consente l'accesso ai dati del database ISTAT. La funzione accetta un JSON di parametri per personalizzare la richiesta e restituisce un set di dati o un messaggio di errore.

L'API è accessibile al seguente endpoint:

https://www.italy-trend.com/api/v1/get_data

Parametri accettati come `json`

id_data (stringa, obbligatorio): Specifica l'ID del dataset che si desidera recuperare.
key (stringa, opzionale): Una chiave opzionale per filtrare i dati contenuti nel dataset.
lang (stringa, opzionale): La lingua dei dati restituiti. I valori possibili sono "it" (predefinito) e "en".
timeout (intero, opzionale): Specifica il tempo massimo, in secondi, per completare la richiesta. Il valore predefinito è 30.

Headers

Le richieste devono essere inviate con headers come segue

headers = {
        "Content-Type": "application/json",
        "Accept": "application/json"
    }

Risposta

La risposta delle chiamate API è un json che rappresenta la tabella richiesta:

Ogni elemento della lista response rappresenta una riga della tabella.
Le chiavi dell'oggetto riga (come territorio, classe di eta, TIME_PERIOD, OBS_VALUE) corrispondono ai nomi delle colonne della tabella.
I valori delle chiavi rappresentano i dati effettivi della tabella per quella riga.

Ecco un esempio di risposta restituita dall'API per una tabella con le colonne territorio, classe di eta, TIME_PERIOD e OBS_VALUE:

response = [
    {
        "territorio": "Lombardia",
        "classe di eta": "18-25",
        "TIME_PERIOD": "2020",
        "OBS_VALUE": 12345.67
    },
    {
        "territorio": "Lombardia",
        "classe di eta": "18-25",
        "TIME_PERIOD": "2021",
        "OBS_VALUE": 12500.89
    },
    {
        "territorio": "Lazio",
        "classe di eta": "18-25",
        "TIME_PERIOD": "2020",
        "OBS_VALUE": 9876.54
    },
    {
        "territorio": "Lazio",
        "classe di eta": "18-25",
        "TIME_PERIOD": "2021",
        "OBS_VALUE": 10023.11
    }
]

Esempi

Ecco alcuni esempi di utilizzo dell'API per accedere ai dati:

Scaricare un'intera tabella (sconsigliato)

import requests
import pandas as pd

id_data = "143_497"  # Prezzi delle abitazioni (Ipab)
url = r"https://www.italy-trend.com/api/v1/get_data"

headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
}

param = {
    "id_data": id_data
}

response = requests.get(url, json=param, headers=headers)
if response.status_code == 200:
    data = response.json()
    df = pd.DataFrame(data)
    print(df)
else:
    print(f"Errore: {response.status_code} - {response.text}")

Nota: Le tabelle possono essere molto grandi, e la richiesta potrebbe andare in timeout a causa della quantità di dati. Si consiglia di utilizzare un key per filtrare i dati.

Scaricare una tabella con l'applicazione di un filtro

Il parametro key consente di applicare un filtro di uguaglianza a una o più colonne della tabella. La chiave può essere costruita seguendo le indicazioni nell'API Builder

Esempio di codice:

import requests
import pandas as pd

id_data = "143_497"  # Prezzi delle abitazioni (Ipab)
key = "A.IT.18.."
url = r"https://www.italy-trend.com/api/v1/get_data"

headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
}

param = {
    "id_data": id_data,
    "key": key
}

response = requests.get(url, json=param, headers=headers)
if response.status_code == 200:
    data = response.json()
    df = pd.DataFrame(data)
    print(df)
else:
    print(f"Errore: {response.status_code} - {response.text}")

Specifica il parametro key per limitare l'ambito dei dati recuperati, riducendo il rischio di timeout e migliorando le prestazioni.

Risorse aggiuntive

Per un elenco completo delle chiavi valide, dataset e dimensioni, consulta l'API Builder.

Per assistenza o richieste, contatta lo sviluppatore del servizio API all'indirizzo lorenzo.mori@hotmail.it

Guida all'utilizzo dell'API get_data di Italy-Trend