API per Sviluppatori

Quick Start

Inizia subito a usare la nostra API con una semplice richiesta GET:

GET https://api.daticomuni.it/v1/comuni

curl -X GET "https://api.daticomuni.it/v1/comuni?limit=10" \
     -H "Accept: application/json"
                

import requests

response = requests.get("https://api.daticomuni.it/v1/comuni?limit=10")
data = response.json()
print(data)
                

Base URL e Versioni

Base URL: https://api.daticomuni.it
Versione corrente: v1
Formato risposta: JSON

Versioni API

v1: Versione stabile corrente
v2: In sviluppo (contattaci per accesso beta)

Endpoint Disponibili

Comuni

GET /v1/comuni

Elenca tutti i comuni con paginazione

GET /v1/comuni/{codice_istat}

Dati dettagliati di un comune specifico

GET /v1/comuni/search

Ricerca comuni per nome

Province

GET /v1/province

Elenca tutte le province

GET /v1/province/{sigla}/comuni

Comuni di una provincia specifica

Regioni

GET /v1/regioni

Elenca tutte le regioni

GET /v1/regioni/{nome}/comuni

Comuni di una regione specifica

Parametri Comuni

Parametro	Tipo	Descrizione	Esempio
`limit`	Integer	Numero massimo di risultati (max: 1000)	`?limit=50`
`offset`	Integer	Numero di risultati da saltare	`?offset=100`
`sort`	String	Campo di ordinamento	`?sort=nome`
`order`	String	Direzione ordinamento (asc/desc)	`?order=desc`
`fields`	String	Campi da includere	`?fields=nome,popolazione`

Formato Risposta

Struttura JSON

{
  "success": true,
  "data": [
    {
      "codice_istat": "058091",
      "nome": "Roma",
      "provincia": "RM",
      "regione": "Lazio",
      "popolazione": 2873494,
      "superficie": 1285.31,
      "latitudine": 41.9028,
      "longitudine": 12.4964,
      "cap": "00100",
      "prefisso": "06"
    }
  ],
  "pagination": {
    "total": 7904,
    "limit": 10,
    "offset": 0,
    "has_next": true
  },
  "timestamp": "2026-01-23T10:30:00Z"
}
                

Campi Disponibili

Campo	Tipo	Descrizione
`codice_istat`	String	Codice ISTAT univoco
`nome`	String	Nome del comune
`provincia`	String	Sigla provincia
`regione`	String	Nome regione
`popolazione`	Integer	Numero abitanti
`superficie`	Float	Superficie in km²
`latitudine`	Float	Coordinata geografica
`longitudine`	Float	Coordinata geografica

Rate Limiting

Per garantire un servizio stabile per tutti, appliciamo i seguenti limiti:

API Gratuita: 100 richieste/ora per IP
API Pro: 10.000 richieste/ora
API Enterprise: Illimitate

Headers Rate Limit

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642952400
                

Quando superi i limiti, riceverai una risposta 429 Too Many Requests.

Gestione Errori

Codici di Errore

Codice	Descrizione	Soluzione
`400`	Bad Request	Verifica parametri richiesta
`404`	Not Found	Risorsa non trovata
`429`	Too Many Requests	Riduci frequenza richieste
`500`	Internal Server Error	Riprotra più tardi

Formato Errore

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "details": "Limit: 100 requests/hour"
  },
  "timestamp": "2026-01-23T10:30:00Z"
}
                

SDK e Librerie

Python

pip install daticomuni-python

from daticomuni import DatiComuniAPI

api = DatiComuniAPI()
comuni = api.get_comuni(limit=10)
print(comuni)
                

JavaScript

npm install daticomuni-js

import { DatiComuniAPI } from 'daticomuni-js';

const api = new DatiComuniAPI();
const comuni = await api.getComuni({ limit: 10 });
console.log(comuni);
                

PHP

composer require daticomuni/php

Supporto e Contatti

Per assistenza tecnica, domande o suggerimenti:

Email: api@daticomuni.it
Documentation: Swagger UI
Status: API Status
GitHub: Client Libraries

API Status

Controlla lo stato attuale dei servizi API:

https://api.daticomuni.it/status