Obiettivo
Spesso hai bisogno di convalidare la posizione di un luogo. Esistono diversi servizi in Google Maps Platform che possono aiutarti in questo caso d'uso. Questo documento ti aiuta a scegliere tra i due servizi principali di convalida della posizione: l'API Address Validation e l'API Geocoding.
L'API Address Validation è un'offerta di Google Maps Platform che aiuta i clienti a verificare se un indirizzo è accurato o meno.
La geocodifica con l'API Geocoding è il processo di conversione degli indirizzi in coordinate geografiche, che puoi utilizzare per posizionare indicatori su una mappa o una posizione sulla mappa.
Una panoramica di alto livello delle differenze tra l'API Address Validation e l'API Geocoding è disponibile qui.
Quando scegliere l'API Address Validation o l'API Geocoding
Note sul diagramma di flusso riportato sopra:
- Il caso d'uso dell'interazione utente si riferisce a quando un utente è presente per interagire con i risultati.
- Place Autocomplete è un'API JavaScript, quindi adatta all'integrazione con le interfacce utente.
- Potresti essere a conoscenza di problemi di qualità dei dati negli indirizzi esistenti. Pertanto, anche se potresti voler solo i geocodici, è consigliabile eseguire queste località tramite l'API Address Validation per correggere i set di dati.
Esistono molte situazioni in cui potresti scegliere, in base all'albero decisionale riportato sopra, di utilizzare un prodotto anziché l'altro. Tuttavia, in altre situazioni potrebbe essere necessario utilizzare entrambi i prodotti per raggiungere i tuoi obiettivi.
Potresti scegliere di utilizzare l'API Address Validation anziché l'API Geocoding quando:
- Esiste un'alta probabilità di dati discutibili o quando ottenere un indirizzo errato avrà un impatto negativo a valle. Questo perché l'API Address Validation fornisce maggiori feedback sul motivo per cui un input non ha ricevuto un risultato di alta precisione.
- Devi correggere gli input dell'utente (ad es. errori di ortografia o campi mancanti), il che aumenta la probabilità di un risultato accurato nell'output.
- La regione target restituisce più metadati dall'API Address Validation rispetto all'API Geocoding, ad esempio la classificazione del tipo di edificio come residenziale o commerciale.
Potresti scegliere di utilizzare la geocodifica anziché l'API Address Validation quando:
- Il tuo obiettivo principale è recuperare la posizione di un indirizzo e l'accuratezza dei singoli indirizzi potrebbe non essere fondamentale.
- Ad esempio, potresti voler generare una mappa termica da un set di dati di grandi dimensioni.
- Hai bisogno di dettagli sulla destinazione iperlocale, come ingressi degli edifici, contorni degli edifici o punti di navigazione per il ritiro e la riconsegna (disponibili con il metodo SearchDestinations nell'API Geocoding v4).
- Hai bisogno di una soluzione globale e l'API Address Validation non è disponibile in tutte le regioni target.
Di seguito sono riportati alcuni esempi che illustrano le funzionalità dell'API Address Validation rispetto all'API Geocoding.
Esempio di indirizzo non valido
1 Fake St, Mountain View, CA 94043, USA
L'API Address Validation suddivide questo input nei suoi singoli componenti dell'indirizzo (via, città, stato e così via). Può anche fornire feedback granulari sul motivo per cui l'indirizzo non è valido fino a un livello PREMISE.
Fake St non esiste a Mountain View, CA, e l'API Address Validation lo riflette nei dettagli a livello di componente restituiti:
{
"componentName": {
"text": "Fake St",
"languageCode": "en"
},
"componentType": "route",
"confirmationLevel":"UNCONFIRMED_BUT_PLAUSIBLE"
}
La proprietà importante da esaminare in questo caso è confirmationLevel. Restituendo UNCONFIRMED_BUT_PLAUSIBLE per Fake St, l'API ha stabilito che una via potrebbe avere questo nome, ma non è in grado di trovare una corrispondenza con i dati dell'indirizzo di supporto.
Utilizzando il risultato dell'API come feedback, si può dedurre che il componente della via di questo input (Fake St) è errato.
Utilizzando lo stesso indirizzo con l'API Geocoding, è in grado di trovare una corrispondenza con "California", come puoi vedere nello screenshot dello strumento di geocodifica che puoi provare qui:
Tuttavia, il risultato è un geocodice dell'intero stato, con un feedback minimo sui componenti dell'input che potrebbero essere errati.
Esempio di errore di ortografia
76 Buckingamm Palace Road, Londn, SW1W 9TQ, GB
L'indirizzo riportato sopra contiene un paio di errori di ortografia, uno nel nome della via e l'altro nella località.
Sia l'API Address Validation sia l'API Geocoding sono in grado di correggere questi errori e ottenere il risultato 76 Buckingham Palace Road, Londra, SW1W 9TQ. Tuttavia, l'API Address Validation può fornire maggiori informazioni sulla procedura.
Dai un'occhiata a uno dei componenti dell'indirizzo con errori di ortografia nell'input:
{
"componentName": {
"text": "Buckingham Palace Road",
"languageCode": "en"
},
"componentType": "route",
"confirmationLevel": "CONFIRMED",
"spellCorrected": true
}
}
L'API Address Validation restituisce un flag per indicare che è stata apportata una correzione al campo. È possibile implementare la logica di business in base a questo flag per ricontrollare la correzione con il fornitore di dati, ad esempio un cliente in un pagamento e-commerce.
Esempio di dati mancanti ed errore di ortografia
Bollschestraße 86, 12587, DE
L'indirizzo riportato sopra contiene un errore di ortografia nel nome della via e manca la città (località) di Berlino.
L'API Address Validation è in grado di correggere entrambi gli errori e restituisce un geocodice a livello di PREMISE e un indirizzo verificato a livello di PREMISE:
Bölschestraße 86, 12587 Berlin, DE
In questo caso, l'API Geocoding non è in grado di superare correttamente gli errori di input e restituisce un risultato di ZERO_RESULTS.
Esempio di metadati dell'indirizzo aggiuntivi
111 8th Avenue Ste 123, New York, NY 10011-5201, US
Questo indirizzo è corretto, ad eccezione del numero dell'unità (Ste 123), che non esiste all'interno dell'edificio.
L'API Address Validation è in grado di convalidare l'indirizzo fino a PREMISE (111 8th Ave) e fornire alcuni metadati sulla proprietà, incluso il fatto che si tratta di un'attività commerciale
locali:
"business": true
Inoltre, il valore dpvConfirmation restituito come parte di uspsData nella risposta è S:
"dpvConfirmation": "S"
Un valore dpvConfirmation di S indica che l'indirizzo è convalidato a livello di PREMISE, ma il numero dell'unità fornito nell'input non è associato a questo indirizzo.
L'API Geocoding non è in grado di fornire queste informazioni.
Informazioni sulla risposta dell'API Geocoding
Panoramica
Se utilizzi l'API Geocoding, il risultato del geocodice contiene vari indizi nella risposta che possono essere utilizzati per comprendere i dettagli dell'indirizzo fornito.
L'API Geocoding funziona risolvendo i componenti dell'indirizzo in una gerarchia.
Ad **esempio, 123 Example Street, Chicago, 60007, USA viene risolto nel seguente ordine:
/ Example Street/ Chicago/ 60007/ USA verrà valutato in questo ordine. In questo caso, la prima corrispondenza è Chicago e, più nello specifico, il codice postale 60007. Pertanto, restituisce il seguente Place_id per questo codice postale:
ChIJwRKzf8ixD4gRHiXqucwr_HQ
L'API Geocode contiene le seguenti informazioni nella risposta:
"partial_match": true,
"place_id": "ChIJwRKzf8ixD4gRHiXqucwr_HQ",
"types": [
"postal_code"
]
L'API Geocoding può confermare a quale tipo di luogo appartiene questo indirizzo. Un elenco degli indirizzi types restituiti dall'API Geocoding è disponibile qui.
Se nessuno dei componenti dell'input viene risolto, l'API restituisce:
{
"results": [],
"status": "ZERO_RESULTS"
}
Se effettui una richiesta solo con l'indirizzo della via senza il numero civico, viene restituito un risultato nel formato:
"types": [
"route"
]
Il che significa che l'API Geocoding non è riuscita a trovare o trovare una corrispondenza con un numero civico.
Nota: per sapere se un indirizzo esiste, controlla se nella risposta dell'API Geocoding sono impostati uno dei parametri (ad esempio types, partial_match, results, status)). In questo modo, il livello di attendibilità che un indirizzo possa esistere aumenterà gradualmente, ma non sarà accurato al 100%. Ecco perché abbiamo bisogno dell'API Address Validation.
Puoi utilizzare le tecniche riportate sopra per aumentare l'attendibilità dell'accuratezza dell'indirizzo da una sola risposta dell'API Geocoding. Tuttavia, a differenza di un risultato dell'API Address Validation, l'API Geocoding non restituirà un feedback esatto per determinare l'accuratezza del risultato.
Tipo di posizione
Per comprendere correttamente questa sezione, devi conoscere i diversi tipi di posizione che potrebbero essere restituiti da una risposta dell'API Geocoding response:
- ROOFTOP indica che il risultato restituito è un geocodice preciso per il quale disponiamo di informazioni sulla posizione accurate fino alla precisione dell'indirizzo della via.
- RANGE_INTERPOLATED indica che il risultato restituito riflette un'approssimazione (di solito su una strada) interpolata tra due punti precisi (ad esempio incroci). I risultati interpolati vengono in genere restituiti quando i geocodici sul tetto non sono disponibili per un indirizzo della via.
- GEOMETRIC_CENTER indica che il risultato restituito è il centro geometrico di un risultato, ad esempio una polilinea (ad esempio una via) o un poligono (regione).
- APPROXIMATE indica che il risultato restituito non è nessuno dei precedenti.
Se un'API Geocoding restituisce un location_type di ROOFTOP o RANGE_INTERPOLATED, non significa necessariamente che l'indirizzo esista. Allo stesso modo, se un'API Geocoding restituisce il flag partial_match impostato su true, potrebbe comunque essere il risultato giusto per te.
Questo tipo di corrispondenza errata è un problema molto difficile da risolvere con l'API Geocoding. Come minimo, potresti prendere in considerazione l'implementazione di una convalida di post-elaborazione di base sul paese e sulla località della richiesta / risposta. Ancora meglio, prova a confrontare gli indirizzi delle vie effettivi per verificare la presenza di errori di ortografia e/o di un indirizzo incompleto.
Nota: se decidi di utilizzare l'API Geocoding, ti consigliamo di eseguire regolarmente controlli della qualità dei dati tra la richiesta iniziale e la risposta dell'API Geocoding.
Corrispondenza parziale e corrispondenza errata
Se un indirizzo è una corrispondenza parziale, il che significa che l'API Geocoding non è riuscita a identificare esattamente l'indirizzo, la risposta contiene:
"partial_match": true,
"types": [
"locality",
"political"
]
Ancora più importante dei tipi di posizione riportati sopra è considerare quando partial_match = true è nella risposta. partial_match indica che l'API Geocoding non ha restituito una corrispondenza esatta per la richiesta originale, anche se è riuscita a trovare una corrispondenza con parte dell'indirizzo richiesto.
Potresti voler esaminare la richiesta originale per verificare la presenza di un indirizzo incompleto. Le corrispondenze parziali si verificano più spesso per gli indirizzi delle vie che non esistono nella località specificata nella richiesta. Le corrispondenze parziali possono essere restituite anche quando una richiesta corrisponde a due o più località nella stessa località.
Ad esempio, "21 Henr St, Bristol, UK" restituisce una corrispondenza parziale sia per Henry Street sia per Henrietta Street. Tieni presente che se una richiesta include un componente dell'indirizzo con errori di ortografia, l'API Geocoding potrebbe suggerire un indirizzo alternativo. I suggerimenti attivati in questo modo non verranno contrassegnati come corrispondenza parziale.
Indirizzi sintetici
L'API Geocoding potrebbe restituire posizioni per indirizzi "sintetici" che non esistono come posizioni precise nel database di Google.
In questi scenari, l'oggetto della risposta contiene spesso un ID luogo lungo e la seguente proprietà: geometry.location_type=APPROXIMATE.
Se riscontri questi indicatori nella risposta, valuta la possibilità di contrassegnare l'indirizzo di input come non valido e di provare a convalidarlo con un altro mezzo.
Nota: questo è un altro esempio in cui, con l'API Address Validation, ricevi un feedback diretto se un indirizzo non esiste.
Informazioni sulla risposta dell'API Address Validation
Esiste già un'ottima documentazione su come comprendere le risposte dell'API Address Validation, quindi non entreremo in ulteriori dettagli qui.
- Una panoramica dell'oggetto della risposta è disponibile qui.
- Una demo che illustra i diversi componenti della risposta è disponibile qui
- Nel documento Convalida dell'indirizzo per il pagamento è presente una descrizione dettagliata di come distinguere gli indirizzi validi da quelli non validi.
Best practice
Specificare la regione
Quando effettui chiamate all'API Address Validation o all'API Geocoding, è una best practice cercare di limitare la regione in cui cercare l'indirizzo. Le due API implementano questa funzionalità in due modi diversi:
API Geocoding - Region Biasing
Se sai che i geocodici si troveranno all'interno di un determinato paese, otterrai risultati molto migliori utilizzando Region Biasing. Ad esempio, se esegui la geocodifica in Canada, ti consigliamo di aggiungere
®ion=caalle richieste per favorire il Canada. Tieni presente che Region Biasing preferisce solo i risultati all'interno della regione. Puoi comunque ottenere risultati al di fuori della regione.API Address Validation - Codice regione
Allo stesso modo, l'API Address Validation produce risultati più accurati se nella richiesta viene passato un codice ISO2 utilizzando il campo
regionCode.
Memorizzare gli ID luogo
Per memorizzare le informazioni di Google Maps Platform sulla posizione per le richieste future, puoi memorizzare l'ID luogo a tempo indeterminato nel tuo database come attributo della posizione. Dovrai effettuare una richiesta Find Place solo una volta per ogni placeID. Puoi anche cercare l'ID luogo ogni volta che un utente richiede i dettagli della transazione.
Per assicurarti di avere sempre le informazioni più aggiornate, aggiorna gli ID luogo ogni 12 mesi utilizzando una richiesta Place Details con il parametro place_id.
Nota: assicurati di consultare anche la guida alle best practice per la geocodifica.
Conclusione
Questo documento descrive le differenze principali tra l'API Address Validation e l'API Geocoding. In sintesi, valuta la possibilità di utilizzare l'API Address Validation quando:
- È necessario un indirizzo postale accurato, soprattutto per la recapitabilità.
- I dati di input sono noti per essere di scarsa qualità. L'API Address Validation è più tollerante agli errori di input, evidenzia i componenti dell'indirizzo non verificabili e apporta correzioni ai dati di input.
- Sono necessarie ulteriori informazioni per un indirizzo, ad esempio Residenziale o Commerciale (disponibile in regioni selezionate).
Passaggi successivi
Scarica il white paper Migliorare pagamento, consegna e operazioni con indirizzi affidabili e guarda il webinar Migliorare pagamento, consegna e operazioni con Address Validation .
Letture consigliate:
- Convalida dell'indirizzo per il pagamento e-commerce
- Documentazione di Place Autocomplete
- Documentazione dell'API Address Validation
- Report di Google Maps Platform
Collaboratori
Google gestisce questo articolo. I seguenti collaboratori lo hanno scritto originariamente.
Autori principali:
Henrik Valve | Solutions Engineer
Thomas Anglaret | Solutions Engineer
Sarthak Ganguly | Solutions Engineer