Comuni Italiani

Libreria Python per cercare informazioni sui comuni italiani usando i dati ISTAT, con arricchimento automatico dei CAP tramite il dataset di Garda Informatica.

Caratteristiche

• Ricerca di un comune per nome, case-insensitive e robusta agli accenti
• Ricerca per codice catastale
• Elenco dei comuni per provincia
• Ricerca inversa per CAP
• Download automatico e aggiornamento del dataset ISTAT
• Download automatico dell'ultimo dataset CAP disponibile da Garda Informatica

Installazione

pip install comuniitaliani

Utilizzo

from comuniitaliani import Comuni

comuni = Comuni()

Cercare un comune per nome

info = comuni.cerca_comune("Agliè")
print(info)

Output di esempio:

{
  "nome": "Agliè",
  "provincia": "Torino",
  "sigla_provincia": "TO",
  "regione": "Piemonte",
  "codice_catastale": "A074",
  "cap": ["10080"]
}

Cercare un comune per codice catastale

info = comuni.cerca_per_codice_catastale("A074")
print(info)

Elencare i comuni di una provincia

torino = comuni.comuni_per_provincia("TO")
print(torino[:3])

Cercare i comuni associati a un CAP

risultati = comuni.cerca_per_cap("10080")
print(risultati)

Output di esempio:

[
  {
    "nome": "Agliè",
    "provincia": "Torino",
    "sigla_provincia": "TO",
    "regione": "Piemonte",
    "codice_catastale": "A074",
    "cap": ["10080"]
  }
]

Note sui CAP

Il campo cap viene restituito sempre come lista:

• un comune può avere più CAP
• uno stesso CAP può essere associato a più comuni

Per questo cerca_per_cap() restituisce una lista di comuni.

L'associazione dei CAP privilegia chiavi affidabili nell'ordine:

• codice ISTAT alfanumerico
• codice ISTAT numerico
• codice catastale
• nome comune + sigla provincia

Non viene usato il solo nome comune, per evitare match ambigui.

Aggiornamento automatico dei dati

Per default la libreria:

• verifica se il CSV ISTAT locale è aggiornato
• include nel pacchetto uno snapshot locale del dataset CAP, utile anche offline
• risolve l'ultimo ZIP disponibile dalla pagina di Garda Informatica
• scarica il dataset CAP solo se la versione remota è cambiata

Se vuoi lavorare solo con file già presenti in locale:

comuni = Comuni(allow_download=False)

Se vuoi disabilitare completamente il layer CAP:

comuni = Comuni(load_cap=False)

Se vuoi indicare esplicitamente un file CAP locale:

comuni = Comuni(cap_csv_file="/percorso/garda_cap.csv", allow_download=False)

Fonti dati

• ISTAT per anagrafica comuni
• Garda Informatica per l'associazione CAP

Compatibilita API

Dalla versione 0.22.1 le funzioni che restituiscono dati di comune includono anche il campo cap. Il campo e sempre una lista, anche quando esiste un solo CAP.

Sviluppo

Installazione dipendenze di sviluppo:

pip install -e . -r requirements-dev.txt

Esecuzione test:

pytest

Licenza

Il progetto è distribuito con licenza MIT. Vedi LICENSE.

Link utili

• Repository GitHub
• PyPI Package
• Dataset ISTAT
• Dataset Garda Informatica