Utilizza l'API Address Validation per elaborare gli indirizzi ad alto volume

Obiettivo

In qualità di sviluppatore, spesso lavori con set di dati contenenti indirizzi dei clienti che potrebbero non essere di buona qualità. Devi assicurarti che gli indirizzi siano corretti per scenari di utilizzo che vanno dalla verifica dell'identità del cliente alla consegna e altro ancora.

L'API Address Validation è un prodotto di Google Maps Platform che puoi utilizzare per convalidare un indirizzo. Tuttavia, elabora un solo indirizzo alla volta. In questo documento, esamineremo come utilizzare la convalida degli indirizzi ad alto volume in diversi scenari, dai test dell'API alla convalida degli indirizzi una tantum e ricorrenti.

Casi d'uso

Ora vedremo i casi d'uso in cui la convalida degli indirizzi ad alto volume è utile.

Test

Spesso è necessario testare l'API Address Validation eseguendo migliaia di indirizzi. Potresti avere gli indirizzi in un file CSV e voler verificare la loro qualità.

Convalida una tantum degli indirizzi

Durante l'onboarding all'API Address Validation, vuoi convalidare il database degli indirizzi esistente in base al database degli utenti.

Convalida ricorrente degli indirizzi

In una serie di scenari è necessario convalidare gli indirizzi su base ricorrente:

• Potresti aver pianificato job per convalidare gli indirizzi per i dettagli acquisiti durante la giornata, ad esempio, dalle registrazioni dei clienti ai dettagli degli ordini e dai programmi di consegna.
• Potresti ricevere dump di dati contenenti indirizzi di reparti diversi, ad esempio dal reparto vendite a quello di marketing. Spesso il nuovo reparto che riceve gli indirizzi vuole convalidarli prima di utilizzarli.
• Potresti raccogliere gli indirizzi durante i sondaggi o varie promozioni e poi integrarli nel sistema online. Vuoi verificare che gli indirizzi siano corretti durante l'inserimento nel sistema.

Approfondimento tecnico

Ai fini di questo documento, si presuppone che:

• Stai chiamando l'API Address Validation con gli indirizzi di un database di clienti (ovvero un database con i dettagli dei clienti)
• Puoi memorizzare nella cache gli indicatori di validità per i singoli indirizzi nel tuo database.
• I flag di validità vengono recuperati dall'API Address Validation quando un singolo cliente accede.

Cache per l'utilizzo in produzione

Quando utilizzi l'API Address Validation, spesso è consigliabile memorizzare nella cache parte della risposta della chiamata all'API. Mentre i nostri Termini di servizio limitano i dati che possono essere memorizzati nella cache, tutti i dati che possono essere memorizzati nella cache dall'API Address Validation devono essere memorizzati nella cache a fronte di un account utente. Ciò significa che i metadati del database, dell'indirizzo o dell'indirizzo devono essere memorizzati nella cache in base all'indirizzo email o a un altro ID principale di un utente.

Per il caso d'uso di convalida degli indirizzi ad alto volume, la memorizzazione nella cache dei dati deve rispettare i Termini specifici del servizio dell'API Address Validation, descritti nella Sezione 11.3. In base a queste informazioni, potrai determinare se l'indirizzo di un utente potrebbe non essere valido, nel qual caso dovrai chiedere all'utente un indirizzo corretto durante la sua prossima interazione con la tua applicazione.

• Dati dall'oggetto AddressComponent
  • confirmationLevel
  • inferred
  • spellCorrected
  • replaced
  • unexpected

Se vuoi memorizzare nella cache eventuali informazioni sull'indirizzo effettivo, questi dati devono essere memorizzati nella cache solo con il consenso dell'utente. In questo modo, l'utente è consapevole del motivo per cui un determinato servizio memorizza il suo indirizzo e accetta i termini di condivisione dell'indirizzo.

Un esempio di consenso dell'utente potrebbe essere un'interazione diretta con un modulo di indirizzo di e-commerce su una pagina di pagamento. Tieni presente che memorizzerai ed elaborerai l'indirizzo nella cache per la spedizione di un pacco.

Con il consenso dell'utente, puoi memorizzare nella cache formattedAddress e altri componenti chiave della risposta. Tuttavia, in uno scenario headless, un utente non può fornire il consenso poiché la convalida dell'indirizzo avviene dal backend. Pertanto, puoi memorizzare nella cache informazioni molto limitate in questo scenario headless.

Comprendere la risposta

Se la risposta dell'API Address Validation contiene i seguenti indicatori, puoi avere la certezza che l'indirizzo di input sia di qualità idonea:

• L'indicatore addressComplete nell'oggetto Verdict è true,
• Il validationGranularity nell'oggetto Verdict è PREMISE o SUB_PREMISE
• Nessuno degli elementi AddressComponent è contrassegnato come:
  • Inferred(Nota: inferred=truepuò verificarsi quando addressComplete=true)
  • spellCorrected
  • replaced
  • unexpected e
• confirmationLevel: Il livello di conferma in AddressComponent è impostato suCONFIRMEDoUNCONFIRMED_BUT_PLAUSIBLE

Se la risposta dell'API non contiene gli indicatori riportati sopra, è probabile che l'indirizzo inserito sia di scarsa qualità e puoi memorizzare nella cache gli indicatori nel database per rifletterlo. Gli indicatori memorizzati nella cache indicano che l'indirizzo nel suo complesso è di scarsa qualità, mentre indicatori più dettagliati come Correzione ortografica indicano il tipo specifico di problema di qualità dell'indirizzo. Alla successiva interazione del cliente con un indirizzo segnalato come di scarsa qualità, puoi chiamare l'API Address Validation con l'indirizzo esistente. L'API Address Validation restituirà l'indirizzo corretto che puoi visualizzare utilizzando una richiesta dell'interfaccia utente. Una volta che il cliente ha accettato l'indirizzo formattato, puoi memorizzare nella cache quanto segue dalla risposta:

• formattedAddress
• postalAddress
• addressComponent componentNames o
• UspsData standardizedAddress

Implementare una convalida dell'indirizzo headless

In base alla discussione precedente:

• Spesso è necessario memorizzare nella cache parte della risposta dell'API Address validation per motivi commerciali.
• Tuttavia, i Termini di servizio di Google Maps Platform limitano i dati che possono essere memorizzati nella cache.

Nella sezione che segue, illustreremo una procedura in due passaggi per la conformità ai Termini di servizio e l'implementazione della convalida degli indirizzi per volumi elevati.

Passaggio 1:

Nel primo passaggio vedremo come implementare uno script di convalida degli indirizzi di alto volume da una pipeline di dati esistente. Questa procedura ti consentirà di memorizzare campi specifici della risposta dell'API di convalida dell'indirizzo in modo conforme ai Termini di servizio.

Diagramma A: il seguente diagramma mostra come una pipeline di dati può essere migliorata con una logica di convalida degli indirizzi ad alto volume.

In base ai Termini di servizio, puoi memorizzare nella cache i seguenti dati diaddressComponent:

• confirmationLevel
• inferred
• spellCorrected
• replaced
• unexpected

Di conseguenza, durante questo passaggio dell'implementazione, memorizzeremo nella cache i campi sopra menzionati in base allo UserID.

Per ulteriori informazioni, consulta i dettagli sulla struttura effettiva dei dati.

Passaggio 2:

Nel passaggio 1 abbiamo raccolto feedback che indicano che alcuni indirizzi nel set di dati di input potrebbero non essere di alta qualità. Nel passaggio successivo, prenderemo questi indirizzi segnalati e li presenteremo all'utente per ottenere il suo consenso a correggere l'indirizzo memorizzato.

Diagramma B: questo diagramma mostra come potrebbe essere un'integrazione end-to-end del flusso di consenso dell'utente:

1. Quando l'utente accede, verifica innanzitutto di aver memorizzato nella cache eventuali flag di convalida nel sistema.
2. Se sono presenti segnalazioni, devi mostrare all'utente un'interfaccia utente per correggere e aggiornare il suo indirizzo.
3. Puoi chiamare nuovamente l'API Address Validation con l'indirizzo aggiornato o memorizzato nella cache e presentare all'utente l'indirizzo corretto per confermare.
4. Se l'indirizzo è di buona qualità, l'API Address Validation restituisce un valore formattedAddress.
5. Puoi presentare l'indirizzo all'utente se sono state apportate correzioni o accettare automaticamente se non ci sono correzioni.
6. Quando l'utente accetta, puoi memorizzare nella cache formattedAddress nel database.

Conclusione

La convalida degli indirizzi ad alto volume è un caso d'uso comune che potresti riscontrare in molte applicazioni. Questo documento tenta di dimostrare alcuni scenari e un pattern di progettazione su come implementare una soluzione di questo tipo in conformità ai Termini di servizio di Google Maps Platform.

Abbiamo inoltre scritto un'implementazione di riferimento della convalida degli indirizzi ad alto volume come libreria open source su GitHub. Dai un'occhiata per iniziare subito a creare con la convalida degli indirizzi ad alto volume. Leggi anche l'articolo sui pattern di progettazione per usare la libreria in diversi scenari.

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:

• Applications of High Volume Address Validation
• Libreria Python su GitHub
• Esplora la demo di Address Validation

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