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 casi d'uso che vanno dalla verifica dell'ID 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 delle API alla convalida degli indirizzi una tantum e ricorrente.

Casi d'uso

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

Test

Spesso vuoi testare l'API Address Validation eseguendo migliaia di indirizzi. Potresti avere gli indirizzi in un file con valori separati da virgole e voler convalidare la qualità degli indirizzi.

Convalida una tantum degli indirizzi

Durante l'onboarding all'API Address Validation, vuoi convalidare il tuo database di indirizzi esistente rispetto al database utenti.

Convalida periodica degli indirizzi

In diversi scenari è necessario convalidare gli indirizzi su base ricorrente:

• Potresti aver pianificato job per convalidare gli indirizzi per i dettagli acquisiti durante il giorno, ad esempio da registrazioni di clienti, dettagli degli ordini, programmi di consegna.
• Potresti ricevere dump di dati contenenti indirizzi di reparti diversi, ad esempio, dalle vendite al marketing. Il nuovo reparto che riceve gli indirizzi spesso vuole convalidarli prima di utilizzarli.
• Potresti raccogliere indirizzi durante i sondaggi o varie promozioni e aggiornarli successivamente nel sistema online. Vuoi verificare che gli indirizzi siano corretti mentre li inserisci nel sistema.

Approfondimento tecnico

Ai fini del presente documento, si presuppone che:

• Stai chiamando l'API Address Validation con indirizzi provenienti da un database clienti (ovvero un database con i dettagli dei clienti)
• Puoi memorizzare nella cache i flag di validità in base ai singoli indirizzi del tuo database.
• I flag di validità vengono recuperati dall'API Address Validation quando un cliente individuale esegue l'accesso.

Cache per l'utilizzo in produzione

Quando utilizzi l'API Address Validation, spesso vuoi memorizzare nella cache una parte della risposta della chiamata API. Sebbene i nostri Termini di servizio limitino 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 in un account utente. Ciò significa che nel database l'indirizzo o i metadati dell'indirizzo devono essere memorizzati nella cache in base all'indirizzo email o a un altro ID principale dell'utente.

Per lo scenario di utilizzo della 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 chiederai 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 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 ed è d'accordo con i termini di condivisione dell'indirizzo.

Un esempio di consenso dell'utente è l'interazione diretta con un modulo di indirizzo di e-commerce in una pagina di pagamento. È previsto che memorizzi nella cache ed elabori l'indirizzo ai fini della 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 inserito sia di qualità accettabile per la consegna:

• Il marcatore addressComplete nell'oggetto Verdict è true,
• validationGranularity nell'oggetto Verdict è PREMISE o SUB_PREMISE
• Nessuno dei 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 i marcatori sopra indicati, l'indirizzo di input era probabilmente di scarsa qualità e puoi memorizzare nella cache i flag nel tuo database per riflettere questo aspetto. I flag memorizzati nella cache indicano che l'indirizzo nel suo complesso è di scarsa qualità, mentre flag più dettagliati come Correzione ortografica indicano il tipo specifico di problema di qualità dell'indirizzo. Alla successiva interazione con un cliente con un indirizzo contrassegnato 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 un prompt della UI. Una volta che il cliente accetta 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 una parte della risposta dell'API Address Validation per motivi aziendali.
• Tuttavia, i Termini di servizio di Google Maps Platform limitano i dati che possono essere memorizzati nella cache.

Nella sezione seguente, descriveremo una procedura in due passaggi su come rispettare i Termini di servizio e implementare la convalida degli indirizzi ad alto volume.

Passaggio 1:

Nel primo passaggio esamineremo come implementare uno script di convalida degli indirizzi ad alto volume da una pipeline di dati esistente. Questa procedura ti consentirà di memorizzare campi specifici della risposta dell'API Address Validation 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.

Ai sensi dei Termini di servizio, puoi memorizzare nella cache i seguenti dati di addressComponent:

• confirmationLevel
• inferred
• spellCorrected
• replaced
• unexpected

Pertanto, durante questo passaggio dell'implementazione memorizzeremo nella cache i campi menzionati in precedenza in base allo UserID.

Per maggiori informazioni, consulta i dettagli sulla struttura dei dati effettivi.

Passaggio 2:

Nel passaggio 1, abbiamo raccolto feedback secondo cui alcuni indirizzi nel set di dati di input potrebbero non essere di alta qualità. Nel passaggio successivo, prenderemo questi indirizzi segnalati e li mostreremo all'utente per ottenere il suo consenso alla correzione dell'indirizzo memorizzato.

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

1. Quando l'utente esegue l'accesso, controlla innanzitutto se hai memorizzato nella cache eventuali flag di convalida nel tuo sistema.
2. Se sono presenti indicatori, devi mostrare all'utente un'interfaccia utente per correggere e aggiornare il suo indirizzo.
3. Puoi chiamare di nuovo l'API Address Validation con l'indirizzo aggiornato o memorizzato nella cache e presentare l'indirizzo corretto all'utente per la conferma.
4. Se l'indirizzo è di buona qualità, l'API Address Validation restituisce un formattedAddress.
5. Puoi presentare l'indirizzo all'utente se sono state apportate correzioni oppure accettarlo automaticamente se non sono state apportate correzioni.
6. Una volta che l'utente accetta, puoi memorizzare nella cache il formattedAddress nel database.

Conclusione

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

Inoltre, abbiamo scritto un'implementazione di riferimento della convalida degli indirizzi ad alto volume come libreria open source su GitHub. Dai un'occhiata per iniziare a creare rapidamente con la convalida degli indirizzi ad alto volume. Visita anche l'articolo sui pattern di progettazione su come utilizzare la libreria in diversi scenari.

Passaggi successivi

Scarica il white paper Migliora pagamento, consegna e operazioni con indirizzi affidabili e guarda il webinar Migliorare pagamento, consegna e operazioni con la convalida degli indirizzi .

Letture consigliate:

• Applicazioni della convalida degli indirizzi ad alto volume
• Libreria Python su GitHub
• Esplora la demo di Address Validation

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