API JSON autenticata con chiave. Base URL: https://apiterzosettore.it/v1
L'API richiede una chiave personale, gratuita per usi non commerciali, di ricerca e giornalistici. Per ottenerla compila il modulo di richiesta indicando nome, organizzazione e caso d'uso.
Tratta la chiave come una password: non pubblicarla in repository o codice client-side.
Passa la chiave nell'header X-API-Key a ogni richiesta.
curl https://apiterzosettore.it/v1/5x1000 \
-H "X-API-Key: LA_TUA_CHIAVE"Le richieste senza chiave valida ricevono 401 Unauthorized.
Tutti gli endpoint accettano richieste GET e restituiscono JSON.
| Metodo | Endpoint | Descrizione |
|---|---|---|
| GET | /enti | Dataset unificato: un ente = anagrafica + 5x1000 + bilanci + digitale + territorio + fondi |
| GET | /enti/{cf} | Profilo completo di un ente, con serie storica 5x1000 |
| GET | /5x1000 | Erogazioni e scelte del 5x1000 (ultimo anno) |
| GET | /5x1000/{cf} | Serie storica 5x1000 di un ente (2006→oggi) |
| GET | /runts | Anagrafica degli enti iscritti al RUNTS |
| GET | /finanziamenti-partiti | Erogazioni ai partiti: donatore, partito, importo, anno (2019-2026) |
| GET | /stats | Statistiche di copertura del dataset (senza chiave) |
Parametri comuni, passati in query string.
| Parametro | Tipo | Descrizione |
|---|---|---|
anno | int | Filtra per anno di riferimento |
regione | string | Filtra per regione |
comune | string | Filtra per comune |
q | string | Ricerca testuale sulla denominazione |
importo_min | float | Importo minimo |
page | int | Numero di pagina (default 1) |
per_page | int | Elementi per pagina (default 50, max 500) |
format | string | json (default) o csv |
Esempio con più filtri:
curl -G https://apiterzosettore.it/v1/5x1000 \
-H "X-API-Key: LA_TUA_CHIAVE" \
-d "anno=2023" \
-d "regione=Lombardia" \
-d "importo_min=10000" \
-d "per_page=100"Le risposte JSON hanno una struttura uniforme con metadati di paginazione.
{
"count": 4821,
"page": 1,
"per_page": 50,
"total_pages": 97,
"results": [
{
"cf": "97XXXXXXXXX",
"denominazione": "Associazione Esempio APS",
"importo": 128450.12,
"scelte": 3120,
"anno": 2023,
"regione": "Lombardia",
"comune": "Milano"
}
]
}L'API usa i codici di stato HTTP standard e un corpo JSON con dettaglio.
| Codice | Significato |
|---|---|
200 | OK |
400 | Parametro non valido |
401 | Chiave mancante o non valida |
404 | Risorsa non trovata |
429 | Troppe richieste (rate limit) |
500 | Errore del server |
{
"error": {
"status": 401,
"message": "Chiave API mancante o non valida."
}
}Rate limit: le richieste sono limitate per chiave. Al superamento della soglia l'API risponde con 429 e l'header Retry-After.
Licenza: i dati sono rilasciati con licenza CC-BY 4.0, salvo diversa indicazione della fonte. Cita sempre la fonte originale e API Terzo Settore.