Creazione di funzionalità di convalida della posizione mediante Google Maps Platform

Obiettivo

Spesso hai la necessità di convalidare la posizione di un luogo. In Google Maps Platform sono disponibili diversi servizi che possono esserti utili 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 è corretto 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 generale delle differenze tra Address Validation e l'API Geocoding è disponibile qui.

Prova ora: visita la console Google Cloud e abilita l'API Address Validation e l'API Places.

Quando scegliere l'API Address Validation o Geocoding

Note sul diagramma di flusso riportato sopra:

• Il caso d'uso dell'interazione con l'utente si riferisce alla presenza di un utente per interagire con i risultati.
• Places 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. Quindi, anche se potresti volere solo i codici geografici, è consigliabile eseguire quelle località tramite l'API Address Validation per correggere i set di dati.

In base alla struttura decisionale sopra riportata, esistono molte situazioni in cui potresti scegliere di utilizzare un prodotto piuttosto che l'altro. Tuttavia, altre situazioni 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 avere dati discutibili oppure un indirizzo errato ha un impatto negativo a valle. Questo perché l'API Address Validation fornisce un feedback maggiore sul motivo per cui un input non ha ricevuto un risultato di precisione elevata.
• Devi correggere gli input dell'utente (ad es. errori ortografici o campi mancanti), in modo da aumentare la probabilità di un risultato preciso nell'output.
• La tua regione target restituisce più metadati dall'API Address Validation rispetto all'API Geocoding, ad esempio per 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 da un grande 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 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 in singoli componenti di 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 di 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 controllare in questo caso è confirmationLevel. Se restituisce UNCONFIRMED_BUT_PLAUSIBLE in corrispondenza di Fake St, l'API ha stabilito che sarebbe possibile avere questo nome come nome di una strada, ma non è possibile associarlo ai dati dell'indirizzo di supporto.

Utilizzando il risultato dell'API come feedback, si può dedurre che il componente di strada di questo input (Fake St) è in errore.

Utilizzando lo stesso indirizzo con l'API Geocoding, può creare una corrispondenza per la "California", come mostrato 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 difettosi.

Esempio di errori ortografici

76 Buckingamm Palace Road, Londn, SW1W 9TQ, GB

L'indirizzo precedente 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 di ottenere il risultato di 76 Buckingham Palace Road, London, SW1W 9TQ, Regno Unito. Tuttavia, l'API Address Validation può fornire maggiori informazioni sulla procedura.

Dai un'occhiata a uno dei componenti dell'indirizzo che è stato digitato in modo errato 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 in una procedura di pagamento e-commerce.

Esempio di errori di ortografia e dati mancanti

Bollschestraße 86, 12587, DE

L'indirizzo precedente contiene un errore ortografico nel nome della via e manca la città di Berlino.

L'API Address Validation è in grado di correggere entrambi questi errori e restituisce un geocodice 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 il risultato ZERO_RESULTS.

Esempio di metadati di indirizzi aggiuntivi

111 8th Avenue Ste 123, New York, NY 10011-5201, USA

Questo indirizzo è corretto, tranne che per il numero dell'unità (Ste 123), che non esiste all'interno dell'edificio.

L'API Address Validation è in grado di convalidare l'indirizzo di PREMISE (111 8th Ave) e fornire alcuni metadati sulla proprietà, tra cui che si tratta di una proprietà 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 di 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 del geocodifica 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 viene risolto nel seguente ordine:

/ Example Street/ Chicago/ 60007/ USA verranno valutate in questo ordine. La prima corrispondenza in questo caso è Chicago e, più in particolare, il codice postale 60007. Di conseguenza, per quel codice postale, viene restituito il seguente Place_id:

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 restituito dall'API Geocoding è disponibile qui.

Se nessuno dei componenti dell'input viene risolto, l'API restituisce:

{
   "results": [],
   "status": "ZERO_RESULTS"
}

Se invii una richiesta solo con l'indirizzo civico senza numero civico, viene restituito un risultato nel modulo:

"types": [
  "route"
]

Ciò significa che l'API Geocoding non è riuscita a trovare o associare un numero civico.

Nota: per sapere se esiste un indirizzo, controlla se uno dei parametri (ad es. types, partial_match, results, status)) è impostato nella risposta dell'API Geocoding. In questo modo aumenterà gradualmente il livello di confidenza che potrebbe esistere un indirizzo, ma non sarà preciso al 100%. Ecco perché abbiamo bisogno dell'API Address Validation.

Puoi utilizzare le tecniche illustrate sopra per aumentare la fiducia nell'accuratezza degli indirizzi 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 conoscere i diversi tipi di località che potrebbero essere restituiti da una risposta dell'API Geocoding:

• ROOFTOP indica che il risultato restituito è un geocodice preciso per il quale le informazioni sulla posizione sono precise con precisione dell'indirizzo.
• RANGE_INTERPOLATED indica che il risultato restituito riflette un'approssimazione (di solito su una strada) interpolata tra due punti precisi (come gli incroci). In genere, i risultati interpolati vengono 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 come una polilinea (ad es. una strada) o un poligono (regione).
• APPROXIMATE indica che il risultato restituito non corrisponde a nessuno dei precedenti.

Se un'API Geocoding restituisce location_type 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 falsa corrispondenza è un problema molto difficile da risolvere con l'API Geocoding. Potresti implementare almeno una convalida post-elaborazione di base nel paese e nella località della richiesta / risposta. Inoltre, confronta gli indirizzi effettivi per errori di ortografia e/o indirizzi incompleti.

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, ovvero che l'API Geocoding non è riuscita a identificare esattamente l'indirizzo, la risposta contiene:

"partial_match": true,
"types": [
           "locality",
           "political"
         ]

Quando partial_match = true c'è nella risposta, è ancora più importante dei tipi di località precedenti. 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 se è presente un indirizzo incompleto. Nella maggior parte dei casi, le corrispondenze parziali si verificano per indirizzi che non esistono all'interno della località specificata nella richiesta. Possono essere restituite corrispondenze parziali anche quando una richiesta corrisponde a due o più sedi 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 di un 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 posizioni per "sintetico" indirizzi che non esistono come posizioni esatte nel database di Google.

In questi scenari, l'oggetto risposta spesso contiene un lungo ID luogo e la seguente proprietà: geometry.location_type=APPROXIMATE.

Se incontri questi indicatori nella risposta, potresti contrassegnare l'indirizzo inserito come non valido e provare a riconvalidarlo con un altro mezzo.

Nota: questo è un altro esempio del caso in cui l'API Address Validation ti invia 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 in dettaglio qui.

• La panoramica dell'oggetto risposta è disponibile qui.
• La demo che illustra i diversi componenti della risposta è disponibile qui
• Nel documento Convalida dell'indirizzo per il pagamento c'è una descrizione dettagliata di come distinguere tra indirizzi corretti e non validi.

Best practice

Specificare l'area geografica

Quando effettui chiamate alle API Address Validation o Geocoding, ti consigliamo di cercare di limitare l'area geografica in cui cercare quell'indirizzo. Le due API implementano questa procedura in due modi diversi:

• API Geocoding - Differenziazione per regione

  Se sai che i codici geografici saranno all'interno di un determinato paese, otterrai risultati molto migliori utilizzando la differenziazione per regione. Ad esempio, se ti occupi di geocodifica in Canada, ti consigliamo di aggiungere &region=ca alle tue richieste per differenziare i dati 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 nella richiesta viene passato un codice ISO2, utilizzando il campo regionCode.

Archiviazione degli ID luogo

Per archiviare informazioni di Google Maps Platform sulla sede per richieste future, puoi memorizzare l'ID luogo a tempo indeterminato nel tuo database come attributo della sede. Dovresti inviare una richiesta Trova luogo una sola volta per ogni ID luogo. Puoi anche cercare l'ID luogo ogni volta che un utente richiede i dettagli della transazione.

Per assicurarti di disporre sempre delle informazioni più aggiornate, aggiorna gli ID luogo ogni 12 mesi utilizzando una richiesta Place Details con il parametro place_id.

Nota: assicurati anche di consultare la guida alle best practice per la geocodifica.

Conclusione

Questo documento descrive le differenze principali tra le API Address Validation e Geocoding. Per riassumere, valuta la possibilità di utilizzare l'API Address Validation quando:

• È necessario un indirizzo postale accurato, soprattutto ai fini della possibilità di recapito.
• I dati di input sono noti per essere di scarsa qualità. L'API Address Validation elimina maggiormente 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 determinate regioni).

Passaggi successivi

Scarica il white paper Migliora pagamento, consegna e operazioni con indirizzi affidabili e guarda il webinar Miglioramento di checkout, consegna e operazioni con Address Validation .

Ulteriori letture suggerite:

• Convalida degli indirizzi per il pagamento e-commerce
• Inserisci la documentazione di Autocomplete
• Documentazione dell'API Address Validation
• Report di Google Maps Platform

Collaboratori

Google gestisce questo articolo. L'ha scritto in origine i seguenti collaboratori.

Autori principali:

Henrik Valve | Ingegnere di soluzioni

Thomas Anglaret | Ingegnere di soluzioni

Sarthak Ganguly | Ingegnere di soluzioni