Comuni ITA API

Legacy project

Questa repository è la versione aggiornata della repository Comuni-ITA-legacy.
È possibile usare quella repository per installare una versione standalone dell'API non gestita con Supabase.

Tramite questa REST API hai accesso ad una lista di tutti i comuni, le province e le regioni italiane. I dati sono ottenuti e aggiornamenti da un sistema di aggiornamento semiautomatico che preleva i dati direttamente dagli archivi ISTAT e integra le informazioni mancanti interrogando Wikidata.
I dati non ottenuti automaticamente dal sistema vengono inoltrati direttamente a me che procedo a verificarli e modificarli manualmente.

L'API è scaricabile e installabile su una propria istanza di Supabase oppure è usufruibile in maniera gratuita all'indirizzo https://axqvoqvbfjpaamphztgd.functions.supabase.co.
Dato che l'API è hostata su un servizio gratuito sarebbe opportuno evitare di sovraccaricare l'API per dare a tutti la possibilità di accedervi.

In questa wiki troverai una spiegazione di come funzionano gli endpoint e di come installare l'API su un server.

La documentazione è disponibile anche all'indirizzo https://comuni-ita.readme.io/

License: MIT
Credits: Logo inpired by: Castle by Jasfart from the Noun Project

Indice

• Endpoints
  • GET /comuni
  • GET /comuni/{regione}
  • GET /comuni/provincia/{provincia}
  • GET /province
  • GET /province/{regione}
  • GET /regioni
• Dettagli sulle regioni e sulle province
• Sistema di paging
• Installazione su server proprio
  • Sistema di aggiornamento

Endpoints

/comuni

Ottieni la lista di tutti i comuni italiani.

Documentazione

/comuni/{regione}

Ottieni la lista di tutti i comuni della regione indicata.

Documentazione

/comuni/provincia/{provincia}

Ottieni la lista di tutti i comuni della provincia indicata.

Documentazione

/province

Ottieni la lista di tutte le province italiane.

Documentazione

/province/{regione}

Ottieni la lista di tutte le province della regione indicata.

Documentazione

/regioni

Ottieni la lista delle regioni italiane.

Documentazione

Dettagli sulle regioni e sulle province

Per evitare incongruenze coi nomi di regioni e province, si consiglia di verificare i nomi attraverso gli endpoint /regioni e /province.
In generale i nomi vanno scritti utilizzando i caratteri speciali come apostrofi, spazi o trattini.

Sistema di paging

A causa delle risorse limitate di Supabase, è stato implementato un sistema di paging per evitare di sovraccaricare il server.
Il sistema limita la risposa a 500 elementi per pagina.

Per ottenere i successivi 500 elementi è necessario specificare il parametro page nell'URL.
È possibile personalizzare il numero di elementi per pagina tramite il parametro pagesize nell'URL (limitato comunque a massimo 500 elementi).

Essendo gli endpoint /regioni e /province molto leggeri, non è necessario specificare il parametro page per ottenere tutti i risultati.

Installazione su server proprio

Tramite questa repo è possibile installare l'API su una propria istanza di Supabase.

Sistema di aggiornamento

Il sistema di aggiornamento della API prevede un sistema di logging tramite un bot Telegram. Il bot serve, oltre che per essere notificati sullo stato dell'aggiornamento da remoto, sia per la risoluzione di eventuali problemi/conflitti occorsi durante il fetch automatico dei dati. Prima di poter installare l'API quindi, crea un bot Telegram tramite BotFather (Puoi chiamarlo come vuoi, il codice per il suo funzionamento è incluso in questa repo).