samurai016/comuni-ita-legacy

Semplice API che permette di ottenere in formato JSON i comuni italiani.

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.

comuni-ita-legacy's Issues

Request: Split Italian and German community names

Please split Italian and German community names instead of concatenating them with a slash.

Richiesta province

Ciao, potrebbe essere interessante , passando la regione, avere la lista delle provincie e poi passando la provicnia avere la lista dei comuni, in modo da caricare meno dati

Possibilità di cercare un comune tramite key

Non so se sia già possibile ma sarebbe comodo poter ottenere un singolo comune tramite query come ad esempio
https://comuni-ita.herokuapp.com/api/comuni?nome=milano

Con risposta

{
        "codice": "015146",
        "nome": "Milano",
        "nomeStraniero": null,
        "codiceCatastale": "F205",
        "cap": "20141",
        "prefisso": "02",
        "provincia": "015",
        "coordinate": {
            "lat": 45.46694564819336,
            "lng": 9.1899995803833
        }
},

Application error

Da oggi mi da errore di Heroku. Come posso risolvere?

Errore Deserializzazione Coordinate

cioa, ho notato che alcune coordinate sono tra apici e altri no quindi quando faccio il deserialize va in errore:

esempio:

{"nome":"Zafferana Etnea","codice":"087055","regione":"sicilia","provincia":"catania","sigla":"CT","codiceCatastale":"M139","cap":"95019","coordinate":{"lat":37.690411,"lng":15.1051709}}

{"nome":"Alì","codice":"083002","regione":"sicilia","provincia":"messina","sigla":"ME","codiceCatastale":"A194","cap":"98020","coordinate":{"lat":"38.02694065","lng":"15.41797276"}}

Prendere tutti i comuni di una regione

Salve, con la nuova versione come è possibile richiedere tutti i comuni di una determinata regione?
Usavo questo url https://comuni-ita.herokuapp.com/api/comuni/sicilia?onlyname=true
Ma mi da Regione inesistente

Wrong postal codes

Please overview the postal codes, as they seem to be not correct in some cases. E.g. Appiano sulla strada del vino return 39050 as postal code. This was once its postal code, but now the correct one would be 39057

Coordinate

ciao , chiedevo se per caso non era interessante anche inserire le coordinate relative al cap

Request: Add phone number prefixes and istat numbers to the communities

Add phone number prefixes and istat numbers to the communities