La geocodifica è il processo di conversione degli indirizzi (come una via) in coordinate geografiche (latitudine e longitudine), che puoi utilizzare per posizionare degli indicatori su una mappa o posizionare la mappa. L'obiettivo di questo documento è chiarire le considerazioni relative alla geocodifica degli indirizzi. Descrive quando è ottimale utilizzare l'API Geocoding e quando conviene utilizzare il servizio di completamento automatico dell'API Places.
In generale, utilizza l'API Geocoding per geocodificare indirizzi completi (ad esempio "48 Pirrama Rd, Pyrmont, NSW, Australia"). Utilizza il servizio Place Autocomplete dell'API Places in caso di geocodifica di indirizzi ambigui (incompleti) o per applicazioni sensibili alla latenza, come quando rispondi all'input dell'utente.
Casi d'uso e suggerimenti sulle API
| Casi d'uso e suggerimenti sulle API | |
|---|---|
| Rispondere in tempo reale all'input dell'utente (compresi gli indirizzi ambigui, incompleti, con formato errato o con errori ortografici inseriti da un utente) | Utilizza il servizio Place Autocomplete dell'API Places per ottenere un ID luogo, quindi l'API Geocoding per geocodificare l'ID luogo in un codice latlng. |
| Sistemi automatici che elaborano indirizzi postali completi e non ambigui (ad esempio "48 Pirrama Rd, Pyrmont, NSW, Australia") | Utilizza il servizio web dell'API Geocoding. |
| Sistemi automatici che elaborano query ambigue (ad esempio indirizzi incompleti, con formattazione scadente o con errori ortografici) | Consiglia ai sistemi automatici di utilizzare il servizio web dell'API Geocoding. Tuttavia, i sistemi automatici con un'elevata percentuale di query ambigue, incomplete o con errori ortografici derivate dall'input utente possono trarre vantaggio dall'aggiunta di un widget interattivo Place Autocomplete per consentire agli utenti di selezionare un risultato ed evitare quindi di scrivere un indirizzo con errori di ortografia. |
| Problemi di latenza tramite l'API Directions o l'API Distanza Matrix, con origini, destinazioni o tappe specificati come stringhe di indirizzi | Riduci la latenza di geocodifica utilizzando il servizio Place Autocomplete dell'API Places per ottenere gli ID luogo, quindi passa questi ID all'API Directions o all'API Distanza Matrix. |
Risposta all'input utente
Le applicazioni che rispondono in tempo reale all'input dell'utente hanno due considerazioni principali che influiscono sulla scelta dell'API:
- In genere, l'input dell'utente comporta l'inserimento progressivo di un indirizzo (ad esempio, "Via Roma 123"), pertanto è utile poter geocodificare indirizzi incompleti e ambigui perché consente all'utente di ottenere un risultato più rapidamente.
- Le applicazioni che rispondono all'input utente sono altamente sensibili alla latenza.
Queste due considerazioni rendono il servizio Place Autocomplete in the Places API ideale per il caso d'uso di risposta all'input utente. Il completamento automatico dei luoghi è progettato per restituire più opzioni possibili e per consentire a un utente di sceglierle. È possibile limitare l'API Places alla ricerca solo di codici geografici o indirizzi, escludendo le attività commerciali. Inoltre, la funzione di ricerca di completamento automatico può essere influenzata in modo da restituire risultati specifici per una località. L'API Places restituisce un ID luogo, che può essere trasmesso come località completamente disambigua al servizio web dell'API Geocoding, che restituisce i dettagli completi dell'indirizzo e geocodifica l'indirizzo in formato latlng. Gli ID luogo possono essere trasmessi anche ad altre API, come l'API Directions e l'API Distanza Matrix (vedi sotto).
La geocodifica degli indirizzi nell'API Geocoding ha una latenza molto maggiore e produce anche risultati meno precisi per query incomplete o ambigue, perciò non è consigliata per applicazioni che devono rispondere in tempo reale all'input dell'utente.
Scopri di più sul servizio Place Autocomplete per Android, iOS, JavaScript e sull' API Places.
Sistemi automatici
Elaborazione da sistemi automatici di indirizzi postali completi, non ambigui: le query non ambigue come stringhe di indirizzi postali complete (ad esempio "48 Pirrama Rd, Pyrmont, NSW, Australia") vengono gestite al meglio dal servizio web dell'API Geocoding. Il backend di geocodifica degli indirizzi offre una maggiore copertura degli indirizzi a livello globale ed è ottimizzato per risultati di alta qualità con questi tipi di query complete e non ambigue.
Elaborazione automatica di query ambigue da parte del sistema automatico: le query ambigue sono quelle che contengono indirizzi formattati in modo errato, indirizzi incompleti o errori ortografici. Per i sistemi automatici, consigliamo di utilizzare il servizio web dell'API Geocoding. Tuttavia, l'API Geocoding non è progettata per gestire query ambigue e potrebbe produrre risultati meno precisi o zero risultati in risposta a query ambigue. Se il tuo sistema automatizzato elabora un'elevata percentuale di query ambigue derivate dall'input utente, puoi trarre vantaggio dall'aggiunta di un elemento interattivo alla tua app utilizzando il servizio Place Autocomplete nell'API Places, poiché è progettato per restituire più opzioni possibili e consentire a un utente di scegliere tra queste. L'API Places restituisce un ID luogo che può essere trasmesso come località completamente disambigua al servizio web dell'API Geocoding, che restituisce i dettagli completi dell'indirizzo e geocodifica l'indirizzo in formato latlng. Scopri di più sul servizio Place Autocomplete per Android, iOS, JavaScript e sull' API Places.
Riduzione della latenza per le API Directions e l'API Distanza Matrix
Quando origini, destinazioni o tappe vengono specificati come stringhe di indirizzi, l'API Directions e l' API Distanza Matrix utilizzano lo stesso backend dell'API Geocoding per geocodificare questi indirizzi prima di calcolare le indicazioni stradali. Questo aumenta significativamente la latenza rispetto alla specifica delle stesse località dei dati latlng o degli ID luogo.
Se la tua applicazione utilizza l'API Directions o l'API Distance Matrix in una situazione sensibile alla latenza, ad esempio in risposta all'input dell'utente, e le tue origini, destinazioni o tappe sono inizialmente specificate come stringhe di indirizzo, ti consigliamo di ridurre al minimo la latenza utilizzando il servizio Place Autocomplete dell'API Places per convertire le stringhe di indirizzo in ID luogo, quindi passare gli ID luogo all'API Directions o all'API Distanza Matrix. Scopri di più sul servizio Place Autocomplete per Android, iOS, JavaScript e sull' API Places. Vedi anche un esempio JavaScript di completamento automatico dei luoghi e indicazioni stradali.
Conclusione
A seconda del caso d'uso, durante la geocodifica di indirizzi, l'utilizzo dell'API Geocoding o del servizio Place Autocomplete in combinazione con l'API Geocoding consente di creare applicazioni che offrono agli utenti risultati di geocodifica accurati e latenza ridotta.
Gestione di errori e nuovi tentativi
Se ricevi risposte UNKNOWN_ERROR, queste sono causate da errori temporanei e risolvili al meglio riprovando dopo un breve ritardo. Consigliamo di utilizzare le
librerie client dei servizi web di Google Maps Platform, che includono la logica per i nuovi tentativi e supportano l'autenticazione del piano Premium di Google Maps Platform.
Il client Java, il client Python, il client Go e il client Node.js per i servizi Google Maps sono librerie client supportate dalla community, disponibili per il download e per i contributi su GitHub, dove puoi anche trovare istruzioni per l'installazione e codice di esempio.
Se ricevi un codice di stato OVER_QUERY_LIMIT in risposta, hai superato i limiti di utilizzo per l'API. Ti consigliamo di provare queste
strategie di ottimizzazione dell'utilizzo.