https://github.com/samurai016/comuni-ita
Semplice API che permette di ottenere i comuni italiani in formato JSON, XML o CSV.
https://github.com/samurai016/comuni-ita
api comuni-italiani deno redoc rest-api supabase supabase-functions typescript
Last synced: 4 months ago
JSON representation
Semplice API che permette di ottenere i comuni italiani in formato JSON, XML o CSV.
- Host: GitHub
- URL: https://github.com/samurai016/comuni-ita
- Owner: Samurai016
- License: mit
- Created: 2022-11-15T10:36:19.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2024-12-11T18:57:19.000Z (over 1 year ago)
- Last Synced: 2024-12-11T19:45:54.134Z (over 1 year ago)
- Topics: api, comuni-italiani, deno, redoc, rest-api, supabase, supabase-functions, typescript
- Language: JavaScript
- Homepage: https://comuni-ita.readme.io
- Size: 861 KB
- Stars: 35
- Watchers: 2
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# [Comuni ITA API](https://comuni-ita.readme.io/)
[](https://comuni-ita.readme.io/)
## ⚡TL;DR
* [https://comuni-ita.nicolorebaioli.dev/comuni](https://comuni-ita.nicolorebaioli.dev/comuni) - Lista dei comuni italiani.
* [https://comuni-ita.nicolorebaioli.dev/province](https://comuni-ita.nicolorebaioli.dev/province) - Lista delle province italiane.
* [https://comuni-ita.nicolorebaioli.dev/regioni](https://comuni-ita.nicolorebaioli.dev/regioni) - Lista delle regioni italiane.
Per ulteriori dettagli su filtri, sorting, paginazione e altri endpoint, prosegui la lettura.
## Indice
- [✨Panoramica](#-panoramica)
- [📚 Endpoint API](#-endpoint-api)
- [GET /comuni](#-comuni)
- [GET /comuni/:regione](#-comuniregione)
- [GET /comuni/provincia/:provincia](#-comuniprovincaprovincia)
- [GET /province](#-province)
- [GET /province/:regione](#-provinceregione)
- [GET /regioni](#-regioni)
- [📊 Parametri di Query](#-parametri-di-query)
- [🚀 Deploy](#-deploy)
## ✨ Panoramica
`comuni-ita` è un'API Node.js leggera e ad alte prestazioni costruita con [Fastify](https://www.fastify.io/). Fornisce accesso istantaneo a un dataset completo di comuni, province e regioni italiane.
I dati sono ottenuti e aggiornati da un sistema semiautomatico che preleva i dati direttamente dagli archivi ISTAT e integra le informazioni mancanti interrogando Wikidata.
L'API è disponibile gratuitamente e senza limitazioni all'indirizzo **[https://comuni-ita.nicolorebaioli.dev/](https://comuni-ita.nicolorebaioli.dev/)** oppure può essere facilmente eseguita in locale o distribuita su qualsiasi piattaforma Node.js o Docker.
La documentazione è disponibile anche all'indirizzo [https://comuni-ita.readme.io/](https://comuni-ita.readme.io/).
> **⚠️ Attenzione ⚠️**
> **Il vecchio link https://axqvoqvbfjpaamphztgd.functions.supabase.co e la vecchia versione v3 basata su Supabase sono temporaneamente disponibili ma d'ora in poi faranno redirect al nuovo dominio e alla nuova versione v4 basata su Fastify.**
> **Le risposte e il funzionamento della versione v3 sono invariati** e non richiedono quindi modifiche ai software che utilizzano l'API, ma si consiglia di aggiornare al più presto alla nuova versione v4 per beneficiare di prestazioni migliorate.
> La versione v3 hostata su Supabase è soggetta a limitazioni di utilizzo e prestazioni, e l'incremento della popolarità dell'API ha portato a superare di gran largo queste limitazioni, **mi aspetto una sospension del progetto v3 su Supabase**, motivo per il quale ho deciso di sviluppare una nuova versione v4 basata su Fastify e hostata su un'infrastruttura più performante e scalabile.
## 📚 Endpoint API
### [ `/comuni`](https://comuni-ita.nicolorebaioli.dev/comuni)
Recupera informazioni dettagliate sui comuni italiani.
#### Filtri
- `codice`: Filtra per codice ISTAT esatto.
- `provincia`: Filtra per nome della provincia (corrispondenza esatta, case-insensitive).
- `regione`: Filtra per nome della regione (corrispondenza esatta, case-insensitive).
- `cap`: Filtra per codice postale (CAP).
- `q`: Ricerca parziale per nome (es. "milano").
#### Esempi
Query per ottenere i primi 10 comuni italiani, ordinati alfabeticamente per nome e mostrando solo il nome, il codice e il CAP.
```http
GET /comuni?regione=lombardia&sort=nome&fields=nome,codice,cap&limit=10
```
Query per ottenere tutti i comuni con CAP 20121.
```http
GET /comuni?cap=20121
```
Query per ottenere tutti i comuni che contengono "milano" nel nome.
```http
GET /comuni?q=milano
```
### [ `/comuni/:regione`](https://comuni-ita.nicolorebaioli.dev/comuni/lombardia)
Recupera informazioni dettagliate sui comuni di una regione specifica.
#### Filtri
- `codice`: Filtra per codice ISTAT esatto.
- `provincia`: Filtra per nome della provincia (corrispondenza esatta, case-insensitive).
- `cap`: Filtra per codice postale (CAP).
- `q`: Ricerca parziale per nome (es. "milano").
#### Esempi
Query per ottenere tutti i comuni lombardi che contengono "milano" nel nome.
```http
GET /comuni/lombardia?q=milano
```
Query per ottenere tutti i comuni della Valle d'Aosta.
```http
GET /comuni/valle d'aosta
GET /comuni/valle-d'aosta
GET /comuni/valle-d-aosta
```
### [ `/comuni/provincia/:provincia`](https://comuni-ita.nicolorebaioli.dev/comuni/provincia/milano)
Recupera informazioni dettagliate sui comuni di una provincia specifica.
#### Filtri
- `codice`: Filtra per codice ISTAT esatto.
- `cap`: Filtra per codice postale (CAP).
- `q`: Ricerca parziale per nome (es. "milano").
#### Esempi
Query per ottenere tutti i comuni della provincia di Milano.
```http
GET /comuni/provincia/milano
```
Query per ottenere tutti i comuni della provincia di Milano che contengono "milano" nel nome.
```http
GET /comuni/provincia/milano?q=milano
```
### [ `/province`](https://comuni-ita.nicolorebaioli.dev/province)
Recupera informazioni dettagliate sulle province italiane.
#### Filtri
- `codice`: Filtra per codice ISTAT esatto.
- `regione`: Filtra per nome della regione (corrispondenza esatta, case-insensitive).
#### Esempi
Query per ottenere tutte le province italiane.
```http
GET /province
```
Query per ottenere tutte le province italiane che contengono "reggio" nel nome.
```http
GET /province?q=reggio
```
### [ `/province/:regione`](https://comuni-ita.nicolorebaioli.dev/province/lombardia)
Recupera informazioni dettagliate sulle province italiane di una regione specifica.
#### Filtri
- `codice`: Filtra per codice ISTAT esatto.
#### Esempi
Query per ottenere tutte le province italiane della regione di Lombardia.
```http
GET /province/lombardia
```
### [ `/regioni`](https://comuni-ita.nicolorebaioli.dev/regioni)
Recupera informazioni dettagliate sulle regioni italiane.
#### Esempi
Query per ottenere tutte le regioni italiane.
```http
GET /regioni
```
## 📊 Parametri di Query
### 🌪️ Ordinamento (Sorting)
Usa il parametro `sort` per ordinare i risultati.
- **Crescente:** `?sort=nome`
- **Decrescente:** `?sort=-nome` (aggiungi il prefisso `-`)
### ✂️ Proiezione (Selezione Campi)
Riduci la dimensione del payload selezionando solo i campi necessari usando `fields`.
- **Esempio:** `?fields=nome,codice,cap`
### 📄 Paginazione
Controlla la quantità di dati restituiti.
- `page`: Numero di pagina da restituire (predefinito: `1`).
- `pagesize`: Numero di elementi per pagina (predefinito: `INFINITE`: vengono restituiti tutti gli elementi).
## 🚀 Deploy
Puoi eseguire il deploy di `comuni-ita` utilizzando ambienti Node.js standard o Docker.
### 🐳 Usando Docker
Forniamo un setup pronto all'uso con **Dockerfile** e **docker-compose**.
1. **Build ed Esecuzione:**
```bash
docker-compose up --build -d
```
2. **Accesso:**
L'API sarà disponibile su `http://localhost:8080`.
### 🟢 Usando Node.js
```bash
git clone https://github.com/Samurai016/Comuni-ITA
cd Comuni-ITA
# Installa le dipendenze e avvia l'API
npm install
npm start
```
L'API sarà disponibile su `http://localhost:8080`.
---
Credits: Logo inpired by: [Castle by Jasfart from the Noun Project](https://thenounproject.com/creator/omataloon/)