Documentazione per sviluppatori

Sviluppa con CUDE Facile

REST API e server MCP per integrare i dati pubblici del circuito nazionale CUDE e le procedure alternative dei Comuni.

CUDE Facile espone API pubbliche e un server MCP per consentire l'integrazione con applicazioni web, chatbot, agenti AI e software di terze parti.

Documentazione REST API Server MCP Playground

Sezione 1

REST API

CUDE Facile REST API v1: pubblica, read-only, risposte JSON. Versionata e stabile — modifiche incompatibili verranno pubblicate come v2 mantenendo la retrocompatibilità.

Pubblica & gratuita

JSONRisposte JSON UTF-8

Base URL

https://cudefacile.it/api/v1

Metodo	Endpoint	Descrizione
GET	/api/v1/comuni	Ricerca Comuni aderenti CUDE o dotati di procedura alternativa.
POST	/api/v1/comuni	Segnala un Comune mancante o richiedi l'inserimento di una procedura alternativa. Equivalente al form 'Richiedi un comune'.
GET	/api/v1/comuni/{slug}	Dettaglio completo di un Comune: dati ufficiali CUDE ed eventuale procedura alternativa.
GET	/api/v1/comuni-geo	Ricerca sul dataset geografico ISTAT dei Comuni italiani (coordinate, codici, contatti, stemma).
GET	/api/v1/comuni-geo/{pro_com_t}	Dettaglio geografico ISTAT di un Comune tramite codice `pro_com_t` (codice_provincia + codice_comune).
GET	/api/v1/territori	Elenco di Regioni e Province coperte dal database.
GET	/api/v1/health	Verifica la disponibilità del servizio e la versione corrente.
GET	/api/v1/openapi.json	Specifica OpenAPI 3.1 completa dell'API. Utile per generare client e importare in Postman/Insomnia.
GET	/api/docs	Documentazione interattiva Swagger/Scalar per esplorare e testare gli endpoint direttamente dal browser.

GET/api/v1/comuniJSON

Ricerca Comuni aderenti CUDE o dotati di procedura alternativa.

Parametri query

Nome	Tipo	Descrizione
`q`	string	Testo di ricerca sul nome del Comune.
`regione`	string	Filtro regione (case-insensitive).
`sigla_provincia`	string	Sigla provincia a 2 lettere (es. BO).
`tipo`	'cude' \| 'alternative'	Filtra per tipo di adesione.
`limit`	integer 1–50	Numero massimo di risultati (default 20).
`offset`	integer ≥ 0	Offset per paginazione.

Esempio richiesta

shell

curl "https://cudefacile.it/api/v1/comuni?q=bologna&limit=5"

Esempio risposta

json

{
  "data": [
    {
      "slug": "bologna-bo",
      "nome_comune": "BOLOGNA",
      "provincia": "BOLOGNA",
      "sigla_provincia": "BO",
      "regione": "EMILIA-ROMAGNA",
      "tipo": "cude",
      "codice_istat": "037006",
      "lat": 44.4949,
      "lon": 11.3426
    }
  ],
  "meta": { "total": 1, "limit": 5, "offset": 0, "has_more": false }
}

POST/api/v1/comuniJSON

Segnala un Comune mancante o richiedi l'inserimento di una procedura alternativa. Equivalente al form 'Richiedi un comune'.

Body JSON

Nome	Tipo	Descrizione
`nome_comune`*	string	Nome del Comune mancante (2–120 caratteri).
`nome_provincia`	string	Nome della provincia (alias: provincia).
`regione`	string	Nome della regione.
`email`	string	Email di contatto (opzionale, deve essere valida).

Esempio richiesta

shell

curl -X POST "https://cudefacile.it/api/v1/comuni" \
  -H "Content-Type: application/json" \
  -d '{
    "nome_comune": "Verghereto",
    "nome_provincia": "Forlì-Cesena",
    "regione": "EMILIA-ROMAGNA",
    "email": "nome.cognome@email.com"
  }'

Esempio risposta

json

{ "status": "received" }

GET/api/v1/comuni/{slug}JSON

Dettaglio completo di un Comune: dati ufficiali CUDE ed eventuale procedura alternativa.

Parametri query

Nome	Tipo	Descrizione
`slug`*	string	Slug del Comune (es. 'bologna-bo').

Esempio richiesta

shell

curl "https://cudefacile.it/api/v1/comuni/bologna-bo"

Esempio risposta

json

{
  "data": {
    "slug": "bologna-bo",
    "tipo": "cude",
    "nome_comune": "BOLOGNA",
    "regione": "EMILIA-ROMAGNA",
    "codice_istat": "037006",
    "lat": 44.4949,
    "lon": 11.3426,
    "adesione_cude": { "data_adesione_cude": "2022-03-01" },
    "procedura_alternativa": null
  }
}

GET/api/v1/comuni-geoJSON

Ricerca sul dataset geografico ISTAT dei Comuni italiani (coordinate, codici, contatti, stemma).

Parametri query

Nome	Tipo	Descrizione
`q`	string	Testo di ricerca sul nome del Comune.
`regione`	string	Filtro regione.
`sigla`	string	Sigla provincia a 2 lettere.
`cod_reg`	integer	Codice ISTAT regione.
`limit`	integer 1–100	Numero massimo di risultati (default 20).
`offset`	integer ≥ 0	Offset per paginazione.

Esempio richiesta

shell

curl "https://cudefacile.it/api/v1/comuni-geo?q=bologna&limit=1"

Esempio risposta

json

{
  "data": [
    {
      "pro_com_t": "037006",
      "comune": "Bologna",
      "sigla": "BO",
      "den_reg": "Emilia-Romagna",
      "lat": 44.4949,
      "lon": 11.3426
    }
  ],
  "meta": { "total": 1, "limit": 1, "offset": 0, "has_more": false }
}

GET/api/v1/comuni-geo/{pro_com_t}JSON

Dettaglio geografico ISTAT di un Comune tramite codice `pro_com_t` (codice_provincia + codice_comune).

Parametri query

Nome	Tipo	Descrizione
`pro_com_t`*	string	Codice ISTAT del Comune (es. '037006').

Esempio richiesta

shell

curl "https://cudefacile.it/api/v1/comuni-geo/037006"

Esempio risposta

json

{
  "data": {
    "pro_com_t": "037006",
    "comune": "Bologna",
    "sigla": "BO",
    "den_reg": "Emilia-Romagna",
    "lat": 44.4949,
    "lon": 11.3426
  }
}

GET/api/v1/territoriJSON

Elenco di Regioni e Province coperte dal database.

Parametri query

Nome	Tipo	Descrizione
`flat`	boolean	Se true, restituisce liste piatte anziché la struttura raggruppata.
`regione`	string	Filtra le province per regione.

Esempio richiesta

shell

curl "https://cudefacile.it/api/v1/territori"

Esempio risposta

json

{
  "data": {
    "regioni": [
      { "nome": "EMILIA-ROMAGNA", "province": [{ "nome": "BOLOGNA", "sigla": "BO" }] }
    ]
  }
}

GET/api/v1/healthJSON

Verifica la disponibilità del servizio e la versione corrente.

Esempio richiesta

shell

curl "https://cudefacile.it/api/v1/health"

Esempio risposta

json

{ "status": "ok", "version": "v1", "timestamp": "2025-01-01T00:00:00.000Z" }

GET/api/v1/openapi.jsonJSON

Specifica OpenAPI 3.1 completa dell'API. Utile per generare client e importare in Postman/Insomnia.

Esempio richiesta

shell

curl "https://cudefacile.it/api/v1/openapi.json"

Esempio risposta

json

{ "openapi": "3.1.0", "info": { "title": "CUDE Facile REST API", "version": "1.0.0" }, "paths": { "...": {} } }

GET/api/docsHTML

Documentazione interattiva Swagger/Scalar per esplorare e testare gli endpoint direttamente dal browser.

Esempio richiesta

shell

open "https://cudefacile.it/api/docs"

Esempio risposta

text

<!-- Pagina HTML interattiva basata su OpenAPI 3.1 -->

Sezione 2

Server MCP

Il server MCP (Model Context Protocol) consente ad agenti AI compatibili — Claude, Cursor, ChatGPT e altri — di interrogare direttamente CUDE Facile come fonte di contesto strutturata.

MCPEndpoint:https://cudefacile.it/mcp

TOOLsearch_comuni

Ricerca Comuni aderenti CUDE e procedure alternative.

Parametri

Nome	Tipo	Descrizione
`query`*	string	Testo di ricerca sul nome del Comune.
`regione`	string	Filtro regione.
`sigla_provincia`	string	Sigla provincia a 2 lettere.
`limit`	integer	Numero massimo di risultati (1–50).

Esempio invocazione

mcp tool call

{
  "name": "search_comuni",
  "arguments": { "query": "bologna", "limit": 5 }
}

TOOLget_comune

Dettaglio completo di un Comune tramite slug.

Parametri

Nome	Tipo	Descrizione
`slug`*	string	Slug del Comune (es. 'bologna-bo').

Esempio invocazione

mcp tool call

{
  "name": "get_comune",
  "arguments": { "slug": "bologna-bo" }
}

TOOLlist_regioni_province

Elenco dei territori disponibili (Regioni e Province).

Esempio invocazione

mcp tool call

{
  "name": "list_regioni_province",
  "arguments": {}
}

Sezione 3

Come iniziare

Nessuna autenticazione richiesta per gli endpoint pubblici. Basta una chiamata HTTP.

JavaScript

javascript

const response = await fetch(
  "https://cudefacile.it/api/v1/comuni?q=bologna"
);

const result = await response.json();

console.log(result);

cURL

shell

curl "https://cudefacile.it/api/v1/comuni?q=bologna" \
  -H "Accept: application/json"

Sezione 4

Versioning

REST API

Server MCP

Le future modifiche incompatibili verranno pubblicate come v2, mantenendo la retrocompatibilità della versione corrente.

Sezione 5

Rate Limit

Al minuto

60 richieste

Al giorno

1000 richieste

I limiti sono per indirizzo IP e potranno evolvere in futuro. Il superamento restituisce HTTP 429 con header Retry-After.

Sezione 6

Licenza e fonti

I dati relativi ai Comuni aderenti CUDE derivano da informazioni pubblicamente disponibili.
CUDE Facile è un progetto indipendente.
CUDE Facile non è affiliato al Ministero delle Infrastrutture e dei Trasporti.
Le procedure alternative sono contenuti editoriali redatti a partire dalle fonti ufficiali dei Comuni.

Sezione 7

Contatti

Emailandrea@cxplayground.it

LinkedInAndrea Previati

GitHubRepository e esempi (in arrivo)