Guida alla convalida di 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'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 Address Validation ad alto volume in diversi scenari, dai test delle API alla convalida degli indirizzi una tantum e ricorrente.

Casi d'uso

Ora vedremo i casi d'uso in cui High Volume Address Validation è utile.

Test

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

Convalida una tantum degli indirizzi

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

Convalida ricorrente degli indirizzi

Esistono diversi scenari che richiedono la convalida degli indirizzi su base ricorrente:

  • Potresti aver pianificato job per convalidare gli indirizzi in base ai dettagli acquisiti durante il giorno, ad esempio dalle registrazioni dei clienti, dai dettagli degli ordini e dalle pianificazioni delle consegne.
  • Potresti ricevere dump di dati contenenti indirizzi di diversi reparti, ad esempio dalle vendite al marketing. Il nuovo reparto che riceve gli indirizzi spesso vuole convalidarli prima di utilizzarli.
  • Potresti raccogliere gli indirizzi durante i sondaggi o varie promozioni e aggiornarli in un secondo momento nel sistema online. Vuoi convalidare gli indirizzi per assicurarti che siano corretti mentre li inserisci nel sistema.

Approfondimento tecnico

Ai fini di questo documento, supponiamo che:

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

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 relazione a 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 di un utente o a un altro ID principale.

Per il caso d'uso di Address Validation ad alto volume, la memorizzazione dei dati nella cache deve seguire i Termini specifici dei servizi 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. In questo caso, chiederai all'utente di fornire 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 è ben 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 è l'interazione diretta con un modulo per l'indirizzo di un sito di e-commerce in una pagina di checkout. È implicito che memorizzerai nella cache ed elaborerai 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, in questo scenario headless puoi memorizzare nella cache informazioni molto limitate.

Comprendi 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 alla consegna:

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

Se la risposta dell'API non contiene gli indicatori sopra indicati, è probabile che l'indirizzo di input sia di scarsa qualità e puoi memorizzare i flag nella cache del database per riflettere questo stato. I flag memorizzati nella cache indicano che l'indirizzo nel suo complesso è di scarsa qualità, mentre i flag più dettagliati, come Correzione ortografica, indicano il tipo specifico di problema di qualità dell'indirizzo. Alla successiva interazione del 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 i seguenti elementi della risposta:

  • formattedAddress
  • postalAddress
  • addressComponent componentNamesoppure
  • UspsData standardizedAddress

Implementa una convalida dell'indirizzo headless

In base alla discussione precedente:

  • Per motivi aziendali, spesso è necessario memorizzare nella cache una parte della risposta dell'API Address Validation.
  • Tuttavia, i Termini di servizio di Google Maps Platform limitano i dati che possono essere memorizzati nella cache.

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

Passaggio 1:

Nel primo passaggio vedremo come implementare uno script di convalida degli indirizzi ad alto volume da una pipeline di dati esistente. Questo processo ti consentirà di archiviare 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 Address Validation ad alto volume.

alt_text

In base ai Termini di servizio, puoi memorizzare nella cache i seguenti dati dell'addressComponent:

  • confirmationLevel
  • inferred
  • spellCorrected
  • replaced
  • unexpected

Pertanto, durante questo passaggio dell'implementazione, memorizzeremo nella cache i campi sopra menzionati rispetto allo UserID.

Per saperne di più, consulta i dettagli sulla struttura dei dati effettiva.

Passaggio 2:

Nel passaggio 1, abbiamo raccolto feedback sul fatto che alcuni indirizzi nel set di dati di input potrebbero non essere di alta qualità. Nel passaggio successivo, mostreremo questi indirizzi segnalati all'utente e otterremo il suo consenso per correggere l'indirizzo memorizzato.

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

alt_text

  1. Quando l'utente è connesso, controlla innanzitutto se hai memorizzato nella cache eventuali flag di convalida nel tuo sistema.
  2. Se sono presenti flag, devi presentare all'utente una UI per correggere e aggiornare l'indirizzo.
  3. Puoi chiamare nuovamente 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 o accettarlo automaticamente se non sono presenti 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 illustrare 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 di Address Validation ad alto volume come libreria open source su GitHub. Dai un'occhiata per iniziare a creare rapidamente con High Volume Address Validation. Consulta anche l'articolo sui pattern di progettazione per l'utilizzo della libreria in diversi scenari.

Passaggi successivi

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

Letture consigliate per approfondire:

Collaboratori

Google gestisce questo articolo. È stato scritto originariamente dai seguenti collaboratori.
Autori principali:

Henrik Valve | Solutions Engineer
Thomas Anglaret | Solutions Engineer
Sarthak Ganguly | Solutions Engineer