La geocodifica è il processo di conversione degli indirizzi (ad esempio una via) in coordinate geografiche (latitudine e longitudine) che puoi utilizzare per posizionare indicatori su una mappa o per posizionare la mappa. Questo documento ha lo scopo di chiarire le considerazioni relative alla geocodifica degli indirizzi. Descrive quando è ottimale utilizzare l'API Geocoding e quando è utile utilizzare il servizio Place Autocomplete dell'API Places.
In generale, utilizza l'API Geocoding per la geocodifica di indirizzi completi (ad esempio, "48 Pirrama Rd, Pyrmont, NSW, Australia"). Utilizza il servizio Place Autocomplete dell'API Places quando esegui il geocoding di indirizzi ambigui (incompleti) o per applicazioni sensibili alla latenza, ad esempio quando rispondi all'input dell'utente.
Casi d'uso e consigli sulle API
| Casi d'uso e consigli sulle API | |
|---|---|
| Rispondere in tempo reale all'input utente (inclusi indirizzi ambigui, incompleti, formattati in modo 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 una latitudine/longitudine. |
| Sistemi automatici che elaborano indirizzi postali completi, univoci (ad esempio, "48 Pirrama Rd, Pyrmont, NSW, Australia") | Utilizza il servizio web dell'API Geocoding. |
| Sistemi automatizzati che elaborano query ambigue (ad esempio, indirizzi incompleti, con formattazione errata o con errori ortografici) | Consiglia di utilizzare il servizio web dell'API Geocoding per i sistemi automatizzati. Tuttavia, i sistemi automatizzati con un alto tasso di query ambigue, incomplete o con errori ortografici derivanti dall'input dell'utente possono trarre vantaggio dall'aggiunta di un widget Place Autocomplete interattivo per consentire agli utenti di selezionare un risultato ed evitare così di scrivere in modo errato un indirizzo. |
| Problemi di latenza durante l'utilizzo dell'API Directions (legacy) o dell'API Distance Matrix (legacy), con origini, destinazioni o tappe intermedie specificate come stringhe di indirizzi | Riduci la latenza di geocodifica utilizzando il servizio Place Autocomplete dell'API Places per ottenere gli ID luogo, quindi passa gli ID luogo all'API Directions (legacy) o all'API Distance Matrix (legacy). |
Rispondi all'input utente
Le applicazioni che rispondono in tempo reale all'input dell'utente hanno due considerazioni principali che influiscono sulla scelta dell'API:
- L'input utente in genere prevede l'inserimento progressivo di un indirizzo (ad esempio "123 Main Street"), pertanto la possibilità di geocodificare indirizzi incompleti e ambigui è utile perché consente all'utente di ottenere un risultato più velocemente.
- Le applicazioni che rispondono all'input utente sono molto sensibili alla latenza.
Queste due considerazioni rendono il servizio Place Autocomplete nell'API Places ideale per il caso d'uso della risposta all'input utente. Place Autocomplete è progettato per restituire più opzioni possibili e consentire a un utente di scegliere tra queste. L'API Places può essere limitata alla ricerca solo di geocodici o indirizzi escludendo le attività. Inoltre, la funzione di ricerca con completamento automatico può essere influenzata in modo da restituire risultati specifici per una località. L'API Places restituisce un ID luogo che può essere passato come località completamente disambiguata al servizio web dell'API Geocoding, che poi restituisce i dettagli completi dell'indirizzo e lo geocodifica in un valore di latitudine e longitudine. Gli ID luogo possono essere passati anche ad altre API, come le API Directions (legacy) e API Distance Matrix (legacy) (vedi Ridurre la latenza).
Il geocoding degli indirizzi nell'API Geocoding ha una latenza molto più elevata e produce anche risultati meno accurati per query incomplete o ambigue, pertanto non è consigliato per le applicazioni che devono rispondere in tempo reale all'input dell'utente.
Scopri di più sul servizio Place Autocomplete per Android, iOS, JavaScript e l' API Places.
Sistemi automatizzati
Sistemi automatici che elaborano indirizzi postali completi e non ambigui: le query non ambigue, come le stringhe di indirizzi postali completi (ad esempio "48 Pirrama Rd, Pyrmont, NSW, Australia"), vengono gestite al meglio dal servizio web 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.
Sistema automatico che elabora query ambigue: le query ambigue sono quelle che contengono indirizzi formattati in modo errato, indirizzi incompleti o errori ortografici. Per i sistemi automatizzati, consigliamo di utilizzare il servizio web API Geocoding. Tuttavia, l'API Geocoding non è progettata per gestire query ambigue e potrebbe produrre risultati meno accurati o nessun risultato in risposta a query ambigue. Se il tuo sistema automatizzato elabora un numero elevato di query ambigue derivate dall'input dell'utente, potresti trarre vantaggio dall'aggiunta di un elemento interattivo alla tua app utilizzando il servizio Place Autocomplete nell'API Places, perché è 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 passato come località completamente disambiguata al servizio web dell'API Geocoding, che poi restituisce i dettagli completi dell'indirizzo e codifica geograficamente l'indirizzo in un valore di latitudine e longitudine. Scopri di più sul servizio Places Autocomplete per Android, iOS, JavaScript e l' API Places.
Ridurre la latenza per l'API Directions (legacy) e l'API Distance Matrix (legacy)
Quando le origini, le destinazioni o i waypoint vengono specificati come stringhe di indirizzo, l'API Directions (legacy) e l' API Distance Matrix (legacy) utilizzano lo stesso backend dell'API Geocoding per geocodificare questi indirizzi prima di calcolare le indicazioni stradali. Ciò aumenta significativamente la latenza rispetto alla specifica delle stesse località come latlng o ID luogo.
Se la tua applicazione utilizza l'API Directions (legacy) o l'API Distance Matrix (legacy) in una situazione sensibile alla latenza, ad esempio in risposta all'input dell'utente, e le origini, le destinazioni o i waypoint sono inizialmente specificati come stringhe di indirizzi, ti consigliamo di ridurre al minimo la latenza utilizzando il servizio Place Autocomplete dell'API Places per convertire le stringhe di indirizzi in ID luogo, quindi passare gli ID luogo all'API Directions (legacy) o all'API Distance Matrix (legacy). Scopri di più sul servizio Place Autocomplete per Android, iOS, JavaScript e l' API Places. Consulta anche un esempio di Place Autocomplete e di indicazioni stradali in JavaScript.
Conclusione
A seconda del caso d'uso, puoi utilizzare l'API Geocoding da sola o in combinazione con il servizio Place Autocomplete. In questo modo puoi creare app che offrono risultati di geocodifica accurati e latenza ridotta.
Gestire gli errori e i tentativi
Se ricevi risposte UNKNOWN_ERROR, queste sono causate da errori temporanei e il modo migliore per gestirle è riprovare dopo un breve ritardo. Ti consigliamo di utilizzare le
librerie client dei servizi web di Google Maps Platform che includono la logica di ripetizione e supportano l'autenticazione di Google Maps Platform Premium Plan.
Il client Java,
il client Python,
il client Go
e il client Node.js
per i servizi Google Maps sono librerie client supportate dall'assistenza della community, disponibili per il download
e i contributi su GitHub, dove troverai anche le istruzioni di installazione e
il codice campione.
Se ricevi un codice di stato OVER_QUERY_LIMIT come risposta, significa che hai superato i limiti di utilizzo per l'API. Ti consigliamo di provare queste
strategie di ottimizzazione dell'utilizzo.