Fino a poco fa il nostro geocoding accettava solo il nome esatto della via. "via nazionale 92 roma" restituiva zero risultati, e un utente che arrivava da Google Maps con l'indirizzo completo restava a mani vuote. A settembre 2026 abbiamo riscritto il motore: ora la query accetta le forme che la gente usa davvero. Qui sotto trovi cosa funziona, con esempi e numeri misurati.
Le forme accettate da /geocode/search
L'endpoint /api/v2/geocode/search ora risolve quattro forme:
- Solo via: "via nazionale"
- Via e civico: "via piacenza 8"
- Via e comune: "via nazionale roma"
- Via, civico e comune: "via piacenza 8 roma", esponenti compresi ("via piacenza 10/A roma")
Il comune può stare in coda alla query e viene riconosciuto fino a tre parole ("via roma 1 castel gandolfo"). Le maiuscole non contano. Un dettaglio tecnico. La ricerca parte dal prefisso del nome strada, quindi "roma" da solo non restituisce niente.
Perché il civico inesistente dà risposta vuota
"via nazionale 100 roma" restituisce zero risultati, ed è il comportamento giusto, perché a Roma via Nazionale arriva al civico 92. L'abbiamo verificato sul database prima di decidere la regola. Un geocoder che per "100" ti restituisce il civico 1 di un altro comune ti fa inserire dati sbagliati in produzione.
La regola è semplice. Se il civico indicato non esiste nel comune indicato, la risposta è vuota. Nessun risultato fuorviante preso da un'altra città.
I numeri prima e dopo
Prima del rilascio abbiamo girato una matrice di 58 casi sull'endpoint live e uno snapshot di regressione su 14 query. Le query che già funzionavano rispondono con le stesse righe nello stesso ordine di prima: zero breaking change.
Sulla latenza, i numeri che contano:
- "via roma" passava da 6,9 secondi a circa 1 secondo
- "via a" da 7,8 secondi a 1,7 secondi
- il peggior caso, "via" da solo, rispondeva con un 502 dopo 8,5 secondi e ora risponde in 1,3 secondi con un 400 esplicito che invita a restringere la ricerca
- la mediana storica del geocoding resta 204 ms, il p95 1.155 ms
I caratteri % e _ sono trattati come testo, non come caratteri jolly: una query con "%via%" non scatena più una scansione completa della tabella indirizzi (27,4 milioni di righe, 20,7 milioni con geometria).
Errori che può restituire
- 400 INVALID_PARAMS: q mancante o sotto i 2 caratteri
- 400 QUERY_TOO_BROAD: query troppo generica, ad esempio "via" senza civico né comune
- 401 API_KEY_REQUIRED o INVALID_API_KEY: chiave mancante o sbagliata
- 429 RATE_LIMITED: limite orario superato, con Retry-After nell'header
Tutti gli errori sono JSON con un campo error e un messaggio leggibile.
Come provarlo in cinque minuti
curl -H "x-api-key: ZRN_LA_TUA_CHIAVE" \
"https://api.zornade.com/api/v2/geocode/search?q=via%20piacenza%208%20roma&limit=5"
La risposta è un JSON con data (gli indirizzi trovati, il primo con formatted_address) e meta con il conteggio. Lo stesso endpoint alimenta il reverse geocoding, che da coordinate restituisce l'indirizzo più vicino.
FAQ
Il geocoding è incluso nel piano gratuito?
Sì, insieme alla ricerca particelle. Il limite è quello del token: 1.000 richieste all'ora.
Come gestisco la risposta vuota?
Una risposta vuota con count 0 può significare civico inesistente o via fuori copertura. Se la via è corretta ma il civico è nuovo (una palazzina appena accatastata), prova senza civico e filtra lato tuo.
Posso cercare per CAP o per toponimo?
No, la ricerca parte dal nome strada. Per i CAP esiste la mappa CAP sul sito, per le particelle c'è l'endpoint dedicato.
Il comune nella query è affidabile?
Sì, il riconoscimento usa l'elenco ufficiale dei comuni con match esatto e prefisso. Per i comuni con nome composto vale la forma completa: "san giuliano milanese".
Il geocoding è il primo passo di ogni integrazione, parliamone con il nostro team.
Foto di copertina: ArtHouse Studio su Pexels