Obiettivo
Spesso hai bisogno di convalidare la posizione 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 dell'indirizzo: l'API Address Validation e l'API Geocoding.
L'API Address Validation è un'offerta di Google Maps Platform che aiuta i clienti a verificare l'accuratezza di un indirizzo.
La geocodifica con l'API Geocoding è il processo di conversione degli indirizzi in coordinate geografiche, che puoi utilizzare per inserire indicatori su una mappa o in una posizione sulla mappa.
Qui puoi trovare una panoramica generale delle differenze tra l'API Address Validation e l'API Geocoding.
Quando scegliere l'API Address Validation o l'API Geocoding
Note sul diagramma di flusso riportato sopra:
- Il caso d'uso 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 nei tuoi indirizzi esistenti. Pertanto, anche se potresti volere solo i codici geografici, ti consigliamo di eseguire queste località tramite l'API Address Validation per correggere i set di dati.
In base all'albero decisionale riportato sopra, in molte situazioni potresti scegliere di utilizzare un prodotto rispetto all'altro. In altre situazioni, però, 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 in cui l'ottenimento 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 di alta precisione.
- Devi correggere gli input degli utenti (ad es. errori ortografici o campi mancanti), il che aumenta la probabilità di ottenere un risultato accurato in uscita.
- La regione di destinazione restituisce più metadati dall'API di convalida degli indirizzi rispetto all'API di geocodifica, ad esempio la classificazione del tipo di edificio come residenziale o commerciale.
Potresti scegliere di utilizzare Geocoding 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, per generare una mappa termica da un ampio set 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 mostrano 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 singoli componenti dell'indirizzo (via, città, stato e così via). Può anche fornire un feedback granulare 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 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 ispezionare in questo caso è confirmationLevel. Restituisce UNCONFIRMED_BUT_PLAUSIBLE per Via Falsa, l'API ha stabilito che sarebbe possibile che una strada abbia questo nome, ma non è possibile trovare una corrispondenza con i dati dell'indirizzo di supporto.
Utilizzando il risultato dell'API come feedback, si può dedurre che il componente della strada di questo input (Fake St) è in errore.
Utilizzando lo stesso indirizzo con l'API Geocoding, è possibile trovare una corrispondenza per "California", come mostrato nello screenshot dello strumento di geocodifica che puoi provare qui:
Tuttavia, il risultato è un codice geografico dell'intero stato, con un feedback minimo su quali componenti dell'input erano potenzialmente difettosi.
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 di convalida degli indirizzi sia l'API di geocodifica 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 ulteriori informazioni sulla procedura.
Dai un'occhiata a uno dei componenti dell'indirizzo che è stato scritto male durante l'inserimento:
{
"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 del pagamento in un sito di e-commerce.
Esempio di dati mancanti ed errori ortografici
Bollschestraße 86, 12587, DE
Nell'indirizzo riportato sopra è presente un errore ortografico nel nome della via e manca la città (località) di Berlino.
L'API Address Validation è in grado di correggere entrambi questi errori e restituisce un codice geografico a livello PREMISE e un indirizzo verificato a livello PREMISE:
Bölschestraße 86, 12587 Berlin, DE
In questo caso, l'API Geocoding non è in grado di superare gli errori di input e restituisce un risultato pari a ZERO_RESULTS.
Esempio di metadati aggiuntivi per gli indirizzi
111 8th Avenue Ste 123, New York, NY 10011-5201, US
L'indirizzo è corretto, tranne per il numero dell'unità (Ste 123), che non esiste all'interno dell'edificio.
L'API Address Validation è in grado di convalidare l'indirizzo PREMISE (111 8th Ave) e fornire alcuni metadati sulla proprietà, ad esempio che si tratta di un'attività commerciale
premises:
"business": true
Inoltre, il valore dpvConfirmation restituito nell'ambito di uspsData nella risposta è S:
"dpvConfirmation": "S"
Un valore dpvConfirmation pari a S indica che l'indirizzo è convalidato a livello PREMISE, ma il numero dell'unità fornito nell'input non è associato a quell'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 della geocodifica 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 verranno valutati in questo ordine. In questo caso, la prima corrispondenza è Chicago e, più specificamente, il codice postale 60007. Pertanto, restituisce il seguente Place_id per quel 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. Qui puoi trovare un elenco degli indirizzi types restituiti dall'API Geocoding.
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 seguente formato:
"types": [
"route"
]
Ciò significa che l'API Geocoding non è riuscita a trovare o a trovare una corrispondenza per un numero civico.
Nota:per sapere se un indirizzo esiste, controlla se uno dei parametri (ad esempio types, partial_match, results, status)) è impostato nella risposta dell'API Geocoding. In questo modo aumenterà gradualmente il livello di confidenza che un indirizzo possa esistere, ma non sarà preciso al 100%. Ecco perché abbiamo bisogno dell'API Address Validation.
Puoi utilizzare le tecniche riportate sopra per aumentare la fiducia nell'accuratezza dell'indirizzo solo da una risposta dell'API Geocoding. Tuttavia, a differenza di un risultato dell'API Address Validation, l'API Geocoding non restituisce un feedback esatto per determinare l'accuratezza del risultato.
Tipo di posizione
Per comprendere correttamente questa sezione, devi conoscere i diversi tipi di località che possono essere restituiti da una risposta dell'API Geocoding:
- ROOFTOP indica che il risultato restituito è un codice geografico preciso per il quale disponiamo di informazioni sulla posizione precise fino all'indirizzo.
- 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 generalmente restituiti quando i codici geografici del tetto non sono disponibili per un indirizzo.
- GEOMETRIC_CENTER indica che il risultato restituito è il centro geometrico di un risultato, ad esempio un polilinea (ad esempio una strada) o un poligono (regione).
- APPROXIMATE indica che il risultato restituito non è nessuno dei valori precedenti.
Se un'API di geocodifica restituisce un location_type di ROOFTOP o RANGE_INTERPOLATED, non significa necessariamente che l'indirizzo esista. Analogamente, se un'API di geocodifica 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, ti consigliamo di implementare alcune verifiche di post-elaborazione di base sul paese e sulla località della richiesta / risposta. Ancora meglio, cerca di confrontare gli indirizzi effettivi per verificare la presenza di errori ortografici e/o di indirizzi incompleti.
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 false corrispondenze
Se un indirizzo è una corrispondenza parziale, ovvero 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 indicati è 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 per parte dell'indirizzo richiesto.
Ti consigliamo di esaminare la richiesta originale per verificare se l'indirizzo è incompleto. Le corrispondenze parziali si verificano più spesso per gli indirizzi 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 che per Henrietta Street. Tieni presente che se una richiesta include un componente dell'indirizzo scritto male, l'API Geocoding potrebbe suggerire un indirizzo alternativo. I suggerimenti attivati in questo modo non verranno contrassegnati come corrispondenze parziali.
Indirizzi sintetici
L'API Geocoding potrebbe restituire località per indirizzi"sintetici" che non esistono come posizioni precise nel database di Google.
In questi casi, l'oggetto response contiene spesso un ID luogo lungo e la seguente proprietà: geometry.location_type=APPROXIMATE.
Se nella risposta riscontri questi indicatori, ti consigliamo di contrassegnare l'indirizzo inserito 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à una documentazione eccellente su come interpretare le risposte dell'API Address Validation, quindi non entreremo in ulteriori dettagli qui.
- Puoi trovare una panoramica dell'oggetto response qui.
- La 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 località
Quando effettui chiamate alle API di convalida degli indirizzi o di geocodifica, è buona norma cercare di limitare l'area geografica in cui cercare l'indirizzo. Le due API lo implementano in due modi diversi:
API Geocoding - Bias di regione
Se sai che i codici geografici si trovano all'interno di un determinato paese, puoi ottenere risultati molto migliori utilizzando la bias di regione. Ad esempio, se esegui il geocoding in Canada, ti consigliamo di aggiungere
®ion=caalle richieste per dare un'impronta in base al Canada. Tieni presente che la funzionalità di bias di regione preferisce solo i risultati all'interno della regione in questione. Puoi comunque ottenere risultati al di fuori della regione.API Address Validation - Region Code
In modo simile, l'API Address Validation produce risultati più accurati se nella richiesta viene passato un codice ISO2 utilizzando il campo
regionCode.
Archiviazione degli ID luogo
Per memorizzare le informazioni sulla posizione di Google Maps Platform per richieste future, puoi memorizzare l'ID luogo a tempo indeterminato nel tuo database come attributo della posizione. Dovresti dover effettuare una richiesta Find Place una sola volta per 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 Dettagli luogo con il parametro place_id.
Nota: assicurati di consultare anche la guida alle best practice per il geocoding.
Conclusione
Questo documento descrive le differenze principali tra le API Address Validation e Geocoding. In sintesi, valuta la possibilità di utilizzare l'API Address Validation quando:
- È necessario un indirizzo postale preciso, soprattutto per motivi di recapito.
- È noto che i dati di input sono di scarsa qualità. L'API Address Validation è più tollerante nei confronti degli errori di input, evidenzia i componenti dell'indirizzo non verificabili e apporta correzioni ai dati di input.
- Per un indirizzo sono necessarie ulteriori informazioni, ad esempio se si tratta di un indirizzo residenziale o commerciale (disponibile in alcune regioni).
Passaggi successivi
Scarica il white paper Migliora il pagamento, la consegna e le operazioni con indirizzi affidabili e guarda il webinar Migliorare il pagamento, la consegna e le operazioni con la convalida dell'indirizzo .
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
Questo articolo è gestito da Google. È stato originariamente scritto dai seguenti collaboratori.
Autori principali:
Henrik Valve | Solutions Engineer
Thomas Anglaret | Solutions Engineer
Sarthak Ganguly | Solutions Engineer