Scopo
Spesso hai bisogno di convalidare la località di un luogo. In Google Maps Platform sono disponibili diversi servizi che possono aiutarti con questo caso d'uso. Questo documento ti aiuta a scegliere tra i due principali servizi di convalida della posizione: API Address Validation e 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 gli indicatori su una mappa o una posizione sulla mappa.
Una panoramica generale delle differenze tra Address Validation e l'API Geocoding è disponibile qui.
Quando scegliere l'API Address Validation e l'API Geocoding
Note sul diagramma di flusso riportato sopra:
- Il caso d'uso delle interazioni con l'utente si riferisce alla presenza di un utente per interagire con i risultati.
- Il completamento automatico di Places è un'API JavaScript, adatta all'integrazione con le interfacce utente.
- Potresti essere a conoscenza di problemi di qualità dei dati negli indirizzi esistenti. Quindi, anche se ti interessano solo i codici geografici, ti consigliamo di eseguire queste posizioni tramite l'API Address Validation per correggere i set di dati.
Esistono molte situazioni in cui potresti scegliere, sulla base della struttura decisionale sopra riportata, di utilizzare un prodotto rispetto all'altro. Altre situazioni, invece, possono comportare l'utilizzo di entrambi i prodotti per raggiungere i tuoi obiettivi.
Puoi scegliere di utilizzare l'API Address Validation anziché l'API Geocoding quando:
- Esiste un'alta probabilità di dati discutibili o situazioni in cui l'inserimento di un indirizzo errato avrà un impatto negativo a valle. Questo perché l'API Address Validation fornisce più feedback sul motivo per cui un input non ha ricevuto un risultato ad alta precisione.
- Devi correggere gli input utente (ad es. errori di ortografia o campi mancanti), per aumentare la probabilità di ottenere risultati accurati nell'output.
- La regione target restituisce un numero maggiore di metadati dall'API Address Validation rispetto all'API Geocoding, come la classificazione del tipo di edificio come residenziale o commerciale.
Puoi scegliere di utilizzare Geocoding anziché l'API Address Validation quando:
- Il tuo obiettivo principale è recuperare la posizione di un indirizzo e la precisione dei singoli indirizzi potrebbe non essere fondamentale.
- Ad esempio, per generare una mappa termica a partire da un grande insieme di dati.
- Hai bisogno di una soluzione globale e l'API Address Validation non è disponibile in tutte le regioni di destinazione.
Di seguito sono riportati alcuni esempi che dimostrano 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 un feedback dettagliato sul motivo per cui l'indirizzo non è valido fino a un livello PREMISE.
Fake St non esiste a Mountain View, in California, e l'API Address Validation riflette questa situazione 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. La restituzione di UNCONFIRMED_BUT_PLAUSIBLE in Fake St, l'API ha stabilito che sarebbe possibile per una strada avere questo nome come nome, ma non è stato possibile associarlo ai dati dell'indirizzo di supporto.
Utilizzando il risultato dell'API come feedback, si può dedurre che il componente stradale di questo input (Fake St) è colpa.
Utilizzando lo stesso indirizzo con l'API Geocoding, può trovare una corrispondenza su "California", come vedi 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 potenzialmente errati.
Esempio di errore ortografico
76 Buckingamm Palace Road, Londn, SW1W 9TQ, GB
L'indirizzo riportato sopra contiene un paio di errori ortografici, uno nel nome della via e l'altro nella località.
Sia l'API Address Validation che l'API Geocoding sono in grado di correggere questi errori e ottenere il risultato di 76 Buckingham Palace Road, London, SW1W 9TQ. Tuttavia, l'API Address Validation può fornire maggiori informazioni sul processo.
Dai un'occhiata a uno dei componenti dell'indirizzo che contiene 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. La logica di business potrebbe essere implementata in base a questo flag per verificare la correzione con il fornitore di dati, ad esempio un cliente al momento di un pagamento e-commerce.
Esempio di dati mancanti ed errori di ortografia
Bollschestraße 86, 12587, DE
L'indirizzo riportato sopra contiene un errore di ortografia nel nome della via e non include la città di Berlino.
L'API Address Validation è in grado di correggere entrambi questi errori e restituisce un geocodice di livello 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 risolvere correttamente gli errori di input e restituisce un risultato di ZERO_RESULTS.
Esempio di metadati aggiuntivi per gli indirizzi
111 8th Avenue Ste 123, New York, NY 10011-5201, USA
L'indirizzo è corretto, ad eccezione del numero dell'appartamento (Ste 123), che non esiste all'interno dell'edificio.
L'API Address Validation è in grado di convalidare l'indirizzo in 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 pari a S indica che l'indirizzo è convalidato a livello di PREMISE, ma il numero di unità fornito nell'input non è associato all'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 degli indirizzi in una gerarchia.
Ad esempio, **123 Example Street, Chicago, 60007, USA si risolve nel seguente ordine:
/ Example Street/ Chicago/ 60007/ USA verranno valutati in quest'ordine. La prima corrispondenza in questo caso è Chicago e, più precisamente, il codice postale 60007. Pertanto, restituisce il seguente Place_id per tale 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. Puoi trovare un elenco di indirizzi types restituiti dall'API Geocoding qui.
Se nessuno dei componenti dell'input viene risolto, l'API restituisce:
{
"results": [],
"status": "ZERO_RESULTS"
}
Se effettui una richiesta solo con l'indirizzo senza numero civico, viene restituito un risultato nel modulo:
"types": [
"route"
]
Ciò significa che l'API Geocoding non è riuscita a trovare o a trovare una corrispondenza con un numero civico.
Nota: per sapere se un indirizzo esiste, verifica se sono stati impostati parametri (ad esempio types e partial_match, results, status) nella risposta dell'API Geocoding). Questo aumenterà gradualmente il livello di confidenza dell'eventuale presenza di un indirizzo, ma non lo renderà completamente preciso. Ecco perché abbiamo bisogno dell'API Address Validation.
Puoi utilizzare le tecniche illustrate sopra per aumentare l'affidabilità dell'accuratezza degli indirizzi derivanti dalla 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 dei risultati.
Tipo di posizione
Per comprendere correttamente questa sezione, devi comprendere i diversi tipi di località che potrebbero essere restituiti da una risposta dell'API Geocoding:
- ROOFTOP indica che il risultato restituito è un geocodice esatto per il quale disponiamo di informazioni sulla posizione accurate fino alla precisione dell'indirizzo.
- RANGE_INTERPOLATED indica che il risultato restituito riflette un'approssimazione (di solito su una strada) interpolata tra due punti precisi (ad esempio gli incroci). I risultati interpolati vengono generalmente restituiti quando i codici geografici sui tetti non sono disponibili per un indirizzo.
- GEOMETRIC_CENTER indica che il risultato restituito è il centro geometrico di un risultato come una polilinea (ad esempio una strada) o un poligono (una regione).
- APPROXIMATE indica che il risultato restituito non è nessuno dei risultati precedenti.
Se un'API Geocoding restituisce un valore location_type di ROOFTOP o RANGE_INTERPOLATED, non significa necessariamente che l'indirizzo esista. Analogamente, se un'API Geocoding restituisce il flag partial_match impostato su true, potrebbe essere comunque il risultato giusto per te.
Questo tipo di falsa corrispondenza è un problema molto difficile da risolvere con l'API Geocoding. Come minimo, potresti considerare l'implementazione di una convalida post-elaborazione di base nel paese e nella località della richiesta / risposta. Meglio ancora, confronta gli indirizzi effettivi per verificare la presenza di errori ortografici e/o un indirizzo incompleto.
Nota: se decidi di utilizzare l'API Geocoding, ti consigliamo di eseguire regolarmente controlli di qualità dei dati tra la richiesta iniziale e la risposta dell'API Geocoding.
Corrispondenza parziale e falsa corrispondenza
Se un indirizzo è una corrispondenza parziale, il che significa che l'API Geocoding non è riuscita a identificarlo esattamente, la risposta contiene:
"partial_match": true,
"types": [
"locality",
"political"
]
Ancora più importante dei tipi di località sopra riportati è 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 far corrispondere parte dell'indirizzo richiesto.
Ti consigliamo di esaminare la richiesta originale per verificare che ci sia un indirizzo incompleto. Le corrispondenze parziali si verificano più spesso per indirizzi che non esistono all'interno della 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 ortografici, 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 località per indirizzi"sintetici" che non esistono come posizioni precise nel database di Google.
In questi scenari, l'oggetto risposta spesso contiene un ID luogo lungo e la seguente proprietà: geometry.location_type=APPROXIMATE.
Se si verificano questi indicatori nella risposta, valuta la possibilità di contrassegnare l'indirizzo di input come non valido e prova a riconvalidarlo con un altro metodo.
Nota: questo è un altro esempio in cui con l'API Address Validation ricevi un feedback diretto se non esiste un indirizzo.
Informazioni sulla risposta dell'API Address Validation
Esiste già un'ottima documentazione su come comprendere le risposte dell'API Address Validation, quindi non entreremo ulteriormente in dettaglio qui.
- Una panoramica dell'oggetto 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 corretti da quelli non validi.
Best practice
Specificare l'area geografica
Quando effettui chiamate alle API Address Validation o Geocoding, è buona norma provare a limitare l'area geografica in cui cercare quell'indirizzo. Le due API implementano questa funzionalità in due modi diversi:
API Geocoding - Differenziazione per regione
Se sai che i codici geografici si troveranno all'interno di un determinato paese, potrai ottenere risultati decisamente migliori utilizzando la Differenziazione per regione. Ad esempio, se stai geocodificando in Canada, ti consigliamo di aggiungere
®ion=caalle tue richieste per la differenziazione verso il Canada. Tieni presente che la differenziazione per regione preferisce solo i risultati all'interno di quella regione. Puoi comunque ricevere risultati al di fuori della regione.API Address Validation - Codice regione
In modo simile, l'API Address Validation produce risultati più accurati se viene passato un codice ISO2 nella richiesta, utilizzando il campo
regionCode.
Memorizzazione degli ID luogo
Per memorizzare informazioni sulla località di Google Maps Platform per richieste future, puoi memorizzare l'ID luogo a tempo indeterminato nel database come attributo della località. Devi effettuare una richiesta Find Place solo una volta per ogni ID luogo. 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 Dettagli luogo con il parametro place_id.
Nota: assicurati di leggere anche la guida alle best practice per la geocodifica.
Conclusione
Questo documento descrive le differenze principali tra le API Address Validation e le API Geocoding. Per riassumere, valuta di utilizzare l'API Address Validation quando:
- È richiesto un indirizzo postale preciso, soprattutto ai fini della consegna.
- È noto che i dati di input sono di scarsa qualità. L'API Address Validation consente di tollerare meglio gli errori di input, evidenzia i componenti degli indirizzi non verificabili e apporta correzioni ai dati di input.
- Sono necessarie ulteriori informazioni per un indirizzo, ad esempio residenziale o commerciale (disponibile in alcune regioni).
Passaggi successivi
Scarica il white paper Migliorare la procedura di pagamento, la consegna e le operazioni con indirizzi affidabili e guardare il webinar Migliorare procedura di pagamento, consegna e operazioni con Address Validation .
Ulteriore lettura suggerita:
- 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 in origine.
Autori principali:
Henrik Valve | Solutions Engineer
Thomas Anglaret | Solutions Engineer
Sarthak Ganguly | Solutions Engineer