Comuni ITA API

Nuova repository

La nuova repository è disponibile qui.

⚠️ ATTENZIONE! Aggiornamento importante ⚠️

A causa delle nuove politiche di Heroku, a partire dal 28 Novembre 2022 l'API non sarà più disponibile all'attuale URL https://comuni-ita.herokuapp.com
Sto lavorando per trovare una soluzione alternativa affinchè l'API possa continuare a rimanere online, in ogni caso l'attuale URL verrà dismesso (non farà redirect su nuovi domini) quindi invito chiunque stia utilizzando l'API a tenere in considerazione questa cosa.
La repository rimarrà attiva e aggiornata e sarà sempre possibile scaricare liberamente il codice e hostarlo su un proprio server.
Ricordo che il progetto è un mio side-project personale, tenuto in vita gratuitamente e che quindi si appoggia solamente a risorse disponibili gratuitamente.

Ulteriori aggiornamenti verranno pubblicati in questa sezione e sull'homepage della documentazione

Aggiornamento 15/11/2022

Ho trovato una soluzione alternativa a Heroku, il progetto è stato spostato su Supabase, la repository è stata migrata e questa su cui stai leggendo questo messaggio è stata archiviata per rimanere disponibile alla lettura ed eventualmente disponibile per coloro che vorranno hostare una loro versione dell'API indipendente da Supabase.
La nuova repository è disponibile qui.

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 un server proprietario oppure è usufruibile in maniera gratuita all'indirizzo https://comuni-ita.herokuapp.com/. 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.herokuapp.com/ sotto forma di documentazione Swagger.

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

Endpoints

/api/comuni

Ottieni la lista di tutti i comuni italiani.

Questo endpoint nelle versioni precedenti alla 2.0.0 era disponibile all'url /comune.
Ora quell'URL è deprecato, rimarrà disponibile, ma si consiglia l'aggiornamento dei propri progetti al nuovo URL.

Documentazione

/api/comuni/{regione}

Ottieni la lista di tutti i comuni della regione indicata.

Documentazione

/api/comuni/provincia/{provincia}

Ottieni la lista di tutti i comuni della provincia indicata.

Documentazione

/api/province

Ottieni la lista di tutte le province italiane.

Documentazione

/api/province/{regione}

Ottieni la lista di tutte le province della regione indicata.

Documentazione

/api/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 /api/regioni e /api/province.
In generale i nomi vanno scritti utilizzando i caratteri speciali come apostrofi, spazi o trattini.

Installazione su server proprio

Tramite questa repo è possibile installare l'API su un proprio server NodeJS.

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).

Prerequisti del server

• MySQL
• Node.js v15
  Verificalo con il comando

  node --version
  # v15.x.x

  Se il comando non viene trovato o la versione installato è precedente alla 15.0.0, procedi ad installare o aggiornare node scaricandolo dal sito ufficiale.

Procedura di installazione

• Nella cartella scelta scarica la presente repo o clonala con il comando

  git clone https://github.com/Samurai016/Comuni-ITA.git

• Crea un file chiamato environment.env con il seguente contenuto:

  TELEGRAM_CHAT=<Chat ID>
  BOT_KEY=<Token del bot>
  MYSQL_HOST=<Server MySQL>
  MYSQL_DATABASE=<Nome del database>
  MYSQL_USERNAME=<Username del database>
  

  • TELEGRAM_CHAT = è l'id della chat, più avanti nella guida ti verrà detto come compilarlo.
  • BOT_KEY = è il token del bot che ti viene fornito da BotFather al momento della creazione del bot, puoi anche ottenerla chiedendola direttamente a BotFather.
• Crea il database MySQL usando il file comuni-ita.sql.
• Avvia il primo aggiornamento dell'API usando il comando

  npm run update

• Invia al bot il comando /start, il bot ti risponderà con il tuo chat ID da inserire nel file environment.env.
• Aggiorna il file environment.env con il chat ID e riavvia l'aggiornamento per popolare il database.
• Una volta completato l'aggiornamento avvia l'API con il comando

  npm start

Ogni volta che vorrai aggiornare l'API ti basterà avviare il comando npm run update.