Questa guida nasce dalle domande che riceviamo ogni settimana dagli sviluppatori che integrano il catasto nei loro prodotti. Niente teoria: autenticazione, errori, limiti e codice Python che funziona così com'è.
Autenticazione: una chiave, un header
Ogni chiamata alle API Zornade porta la chiave nell'header x-api-key. La chiave si crea in un minuto dalla pagina API di Zornade: servono account gratuito e un nome per il token.
curl -H "x-api-key: ZRN_LA_TUA_CHIAVE" \
"https://api.zornade.com/api/v2/parcels/3263001"
Senza chiave la risposta è un 401 con errore API_KEY_REQUIRED. Con chiave sbagliata o scaduta, 401 con INVALID_API_KEY. Gli errori hanno sempre la stessa forma:
{
"error": "CODICE_ERRORE",
"message": "Spiegazione leggibile"
}
Il piano gratuito e i limiti
Il piano gratuito include 1.000 richieste all'ora per token, con finestra scorrevole. Se superi il limite arriva un 429 con l'errore RATE_LIMITED e due header utili: Retry-After (secondi da aspettare) e l'orario di reset. Il consiglio pratico è di gestire il 429 con un backoff esponenziale, non di rilanciare subito.
Sulle 210.009 richieste registrate dal nostro sistema, il 98,8% ha risposto 200. La latenza media è 414 ms e il p95 è 730 ms: numeri di produzione, aggiornati a settembre 2026.
Ricerca di una particella
L'endpoint /parcels/{id} accetta l'identificativo catastale e restituisce geometria e dati censuari. In Python:
import requests
r = requests.get(
"https://api.zornade.com/api/v2/parcels/3263001",
headers={"x-api-key": "ZRN_LA_TUA_CHIAVE"},
timeout=10,
)
print(r.status_code)
print(r.json()["data"]["cadastral"])
Con include=all la risposta aggiunge rischio idrogeologico, zona OMI, demografia, solare e redditi della sezione. La copertura sono gli 85,2 milioni di particelle di 7.899 comuni, venti regioni, 107 province.
Geocoding di un indirizzo
L'endpoint /geocode/search ha cambiato comportamento a settembre 2026 e ora accetta le forme che prima restituivano zero risultati:
import requests
r = requests.get(
"https://api.zornade.com/api/v2/geocode/search",
params={"q": "via nazionale 92 roma", "limit": 5},
headers={"x-api-key": "ZRN_LA_TUA_CHIAVE"},
timeout=10,
)
print(r.json()["data"][0]["formatted_address"])
print(r.json()["meta"]["count"])
Funzionano via e civico, via e comune, via con civico e comune, esponente. Se il civico non esiste nel comune la risposta è vuota, senza risultati fuorvianti di altri comuni. La latenza mediana del geocoding è 204 ms, il p95 1.155 ms.
Reverse geocoding
Da coordinate a indirizzo, con raggio regolabile:
r = requests.get(
"https://api.zornade.com/api/v2/geocode/reverse",
params={"lat": 41.9009, "lng": 12.4833, "radius": 100, "limit": 5},
headers={"x-api-key": "ZRN_LA_TUA_CHIAVE"},
timeout=10,
)
Lat e lng devono stare dentro i confini italiani (35.5-47.5 di latitudine, 6.0-19.0 di longitudine), altrimenti arriva un 400 esplicito.
Errori da gestire nel client
Il client deve trattare almeno questi cinque casi: 401 chiave mancante o invalida, 429 limite orario, 400 parametri errati, 403 scope insufficiente, 502 errore temporaneo del database. I primi quattro sono deterministici, il quinto si ritenta una volta sola dopo un secondo.
FAQ
Serve una libreria ufficiale?
No, gli endpoint sono REST puri con risposte JSON e GeoJSON: vanno bene requests in Python, fetch in JavaScript, qualunque client HTTP. L'OpenAPI 3.1 completa è pubblica su /api/v2/openapi.json.
Posso usare le API in produzione?
Sì, il piano gratuito è pensato per sviluppo e volumi bassi. Per i volumi enterprise esiste un piano a pagamento con limiti più alti e supporto dedicato.
Come faccio a sapere quando cambio endpoint?
Le API sono alla versione 2 e gli endpoint stabili non cambiano senza preavviso. La documentazione OpenAPI è la fonte da cui generare i client.
Il geocoding accetta anche il solo nome del comune?
No, serve almeno il nome della via. Una query come "roma" restituisce una risposta vuota, per scelta: il prefisso del nome strada è il punto di partenza della ricerca.
Se stai integrando il catasto in un gestionale o in un portale, il nostro team sviluppo fa la prima integrazione insieme a te.