{"id":25412266,"url":"https://github.com/samurai016/comuni-ita","last_synced_at":"2026-02-10T01:10:45.653Z","repository":{"id":63729461,"uuid":"566277187","full_name":"Samurai016/Comuni-ITA","owner":"Samurai016","description":"Semplice API che permette di ottenere i comuni italiani in formato JSON, XML o CSV.","archived":false,"fork":false,"pushed_at":"2024-12-11T18:57:19.000Z","size":882,"stargazers_count":35,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-12-11T19:45:54.134Z","etag":null,"topics":["api","comuni-italiani","deno","redoc","rest-api","supabase","supabase-functions","typescript"],"latest_commit_sha":null,"homepage":"https://comuni-ita.readme.io","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Samurai016.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-15T10:36:19.000Z","updated_at":"2024-12-11T18:57:23.000Z","dependencies_parsed_at":"2024-06-25T18:31:01.837Z","dependency_job_id":"93b5d7bf-7124-4623-b4b9-8c9e7fe236da","html_url":"https://github.com/Samurai016/Comuni-ITA","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Samurai016%2FComuni-ITA","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Samurai016%2FComuni-ITA/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Samurai016%2FComuni-ITA/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Samurai016%2FComuni-ITA/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Samurai016","download_url":"https://codeload.github.com/Samurai016/Comuni-ITA/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239120669,"owners_count":19585065,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","comuni-italiani","deno","redoc","rest-api","supabase","supabase-functions","typescript"],"created_at":"2025-02-16T11:18:30.957Z","updated_at":"2026-02-10T01:10:45.645Z","avatar_url":"https://github.com/Samurai016.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/logo.png\" alt=\"Comuni ITA Logo\" /\u003e\n\u003c/p\u003e\n\n# [Comuni ITA API](https://comuni-ita.readme.io/)\n\n![Versione](https://img.shields.io/github/v/release/Samurai016/Comuni-ITA?style=flat-square\u0026label=versione)\n![Licenza](https://img.shields.io/github/license/Samurai016/Comuni-ITA?style=flat-square\u0026label=licenza)\n[![Leggi la documentazione](https://img.shields.io/badge/Leggi%20la%20documentazione-passing?style=flat-square\u0026logo=Read%20the%20Docs\u0026labelColor=8CA1AF\u0026color=8CA1AF\u0026logoColor=white)](https://comuni-ita.readme.io/)\n\n## ⚡TL;DR\n\n* [https://comuni-ita.nicolorebaioli.dev/comuni](https://comuni-ita.nicolorebaioli.dev/comuni) - Lista dei comuni italiani.\n* [https://comuni-ita.nicolorebaioli.dev/province](https://comuni-ita.nicolorebaioli.dev/province) - Lista delle province italiane.\n* [https://comuni-ita.nicolorebaioli.dev/regioni](https://comuni-ita.nicolorebaioli.dev/regioni) - Lista delle regioni italiane.\n\nPer ulteriori dettagli su filtri, sorting, paginazione e altri endpoint, prosegui la lettura.\n\n## Indice\n\n- [✨Panoramica](#-panoramica)\n- [📚 Endpoint API](#-endpoint-api)\n  - [GET /comuni](#-comuni)\n  - [GET /comuni/:regione](#-comuniregione)\n  - [GET /comuni/provincia/:provincia](#-comuniprovincaprovincia)\n  - [GET /province](#-province)\n  - [GET /province/:regione](#-provinceregione)\n  - [GET /regioni](#-regioni)\n- [📊 Parametri di Query](#-parametri-di-query)\n- [🚀 Deploy](#-deploy)\n\n## ✨ Panoramica\n\n`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.\n\nI dati sono ottenuti e aggiornati da un sistema semiautomatico che preleva i dati direttamente dagli archivi ISTAT e integra le informazioni mancanti interrogando Wikidata.\n\nL'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.\n\nLa documentazione è disponibile anche all'indirizzo [https://comuni-ita.readme.io/](https://comuni-ita.readme.io/).\n\n\n\u003e **⚠️ Attenzione ⚠️**\n\u003e **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.**  \n\u003e **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.  \n\u003e 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.\n\n## 📚 Endpoint API\n\n### [![GET](https://img.shields.io/static/v1?label=%20\u0026message=GET\u0026color=187bdf\u0026style=flat-square) `/comuni`](https://comuni-ita.nicolorebaioli.dev/comuni)\n\nRecupera informazioni dettagliate sui comuni italiani.\n\n#### Filtri\n\n- `codice`: Filtra per codice ISTAT esatto.\n- `provincia`: Filtra per nome della provincia (corrispondenza esatta, case-insensitive).\n- `regione`: Filtra per nome della regione (corrispondenza esatta, case-insensitive).\n- `cap`: Filtra per codice postale (CAP).\n- `q`: Ricerca parziale per nome (es. \"milano\").\n\n#### Esempi\n\nQuery per ottenere i primi 10 comuni italiani, ordinati alfabeticamente per nome e mostrando solo il nome, il codice e il CAP.\n\n```http\nGET /comuni?regione=lombardia\u0026sort=nome\u0026fields=nome,codice,cap\u0026limit=10\n```\n\nQuery per ottenere tutti i comuni con CAP 20121.\n\n```http\nGET /comuni?cap=20121\n```\n\nQuery per ottenere tutti i comuni che contengono \"milano\" nel nome.\n\n```http\nGET /comuni?q=milano\n```\n\n### [![GET](https://img.shields.io/static/v1?label=%20\u0026message=GET\u0026color=187bdf\u0026style=flat-square) `/comuni/:regione`](https://comuni-ita.nicolorebaioli.dev/comuni/lombardia)\n\nRecupera informazioni dettagliate sui comuni di una regione specifica.\n\n#### Filtri\n\n- `codice`: Filtra per codice ISTAT esatto.\n- `provincia`: Filtra per nome della provincia (corrispondenza esatta, case-insensitive).\n- `cap`: Filtra per codice postale (CAP).\n- `q`: Ricerca parziale per nome (es. \"milano\").\n\n#### Esempi\n\nQuery per ottenere tutti i comuni lombardi che contengono \"milano\" nel nome.\n\n```http\nGET /comuni/lombardia?q=milano\n```\n\nQuery per ottenere tutti i comuni della Valle d'Aosta.\n\n```http\nGET /comuni/valle d'aosta\nGET /comuni/valle-d'aosta\nGET /comuni/valle-d-aosta\n```\n\n### [![GET](https://img.shields.io/static/v1?label=%20\u0026message=GET\u0026color=187bdf\u0026style=flat-square) `/comuni/provincia/:provincia`](https://comuni-ita.nicolorebaioli.dev/comuni/provincia/milano)\n\nRecupera informazioni dettagliate sui comuni di una provincia specifica.\n\n#### Filtri\n\n- `codice`: Filtra per codice ISTAT esatto.\n- `cap`: Filtra per codice postale (CAP).\n- `q`: Ricerca parziale per nome (es. \"milano\").\n\n#### Esempi\n\nQuery per ottenere tutti i comuni della provincia di Milano.\n\n```http\nGET /comuni/provincia/milano\n```\n\nQuery per ottenere tutti i comuni della provincia di Milano che contengono \"milano\" nel nome.\n\n```http\nGET /comuni/provincia/milano?q=milano\n```\n\n### [![GET](https://img.shields.io/static/v1?label=%20\u0026message=GET\u0026color=187bdf\u0026style=flat-square) `/province`](https://comuni-ita.nicolorebaioli.dev/province)\n\nRecupera informazioni dettagliate sulle province italiane.\n\n#### Filtri\n\n- `codice`: Filtra per codice ISTAT esatto.\n- `regione`: Filtra per nome della regione (corrispondenza esatta, case-insensitive).\n\n#### Esempi\n\nQuery per ottenere tutte le province italiane.\n\n```http\nGET /province\n```\n\nQuery per ottenere tutte le province italiane che contengono \"reggio\" nel nome.\n\n```http\nGET /province?q=reggio\n```\n\n### [![GET](https://img.shields.io/static/v1?label=%20\u0026message=GET\u0026color=187bdf\u0026style=flat-square) `/province/:regione`](https://comuni-ita.nicolorebaioli.dev/province/lombardia)\n\nRecupera informazioni dettagliate sulle province italiane di una regione specifica.\n\n#### Filtri\n\n- `codice`: Filtra per codice ISTAT esatto.\n\n#### Esempi\n\nQuery per ottenere tutte le province italiane della regione di Lombardia.\n\n```http\nGET /province/lombardia\n```\n\n### [![GET](https://img.shields.io/static/v1?label=%20\u0026message=GET\u0026color=187bdf\u0026style=flat-square) `/regioni`](https://comuni-ita.nicolorebaioli.dev/regioni)\n\nRecupera informazioni dettagliate sulle regioni italiane.\n\n#### Esempi\n\nQuery per ottenere tutte le regioni italiane.\n\n```http\nGET /regioni\n```\n\n## 📊 Parametri di Query\n\n### 🌪️ Ordinamento (Sorting)\n\nUsa il parametro `sort` per ordinare i risultati.\n\n- **Crescente:** `?sort=nome`\n- **Decrescente:** `?sort=-nome` (aggiungi il prefisso `-`)\n\n### ✂️ Proiezione (Selezione Campi)\n\nRiduci la dimensione del payload selezionando solo i campi necessari usando `fields`.\n\n- **Esempio:** `?fields=nome,codice,cap`\n\n### 📄 Paginazione\n\nControlla la quantità di dati restituiti.\n\n- `page`: Numero di pagina da restituire (predefinito: `1`).\n- `pagesize`: Numero di elementi per pagina (predefinito: `INFINITE`: vengono restituiti tutti gli elementi).\n\n## 🚀 Deploy\n\nPuoi eseguire il deploy di `comuni-ita` utilizzando ambienti Node.js standard o Docker.\n\n### 🐳 Usando Docker\n\nForniamo un setup pronto all'uso con **Dockerfile** e **docker-compose**.\n\n1.  **Build ed Esecuzione:**\n    ```bash\n    docker-compose up --build -d\n    ```\n2.  **Accesso:**\n    L'API sarà disponibile su `http://localhost:8080`.\n\n### 🟢 Usando Node.js\n\n```bash\ngit clone https://github.com/Samurai016/Comuni-ITA\ncd Comuni-ITA\n\n# Installa le dipendenze e avvia l'API\nnpm install\nnpm start\n```\n\nL'API sarà disponibile su `http://localhost:8080`.\n\n---\n\nCredits: Logo inpired by: [Castle by Jasfart from the Noun Project](https://thenounproject.com/creator/omataloon/)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamurai016%2Fcomuni-ita","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamurai016%2Fcomuni-ita","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamurai016%2Fcomuni-ita/lists"}