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

Scopo

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 solo un indirizzo alla volta. In questo documento scopriremo come utilizzare la convalida degli indirizzi a volume elevato 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 la funzionalità High Volume Address Validation è utile.

Test in corso

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 verificare la qualità degli indirizzi.

Convalida una tantum degli indirizzi

Durante l'onboarding per l'API Address Validation, vuoi convalidare il database di indirizzi esistente confrontandolo con il database degli utenti.

Convalida ricorrente degli indirizzi

Vari scenari richiedono la convalida degli 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 diversi reparti, ad esempio dalle vendite al marketing. Spesso, il nuovo reparto che riceve gli indirizzi desidera convalidarli prima dell'uso.
  • Puoi raccogliere gli indirizzi durante i sondaggi o in varie promozioni e in seguito durante l'aggiornamento nel sistema online. Verifica che gli indirizzi siano corretti mentre li inserisci nel sistema.

Approfondimento tecnico

Ai fini del presente documento, si suppone 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 i flag di validità in corrispondenza di singoli indirizzi nel tuo database.
  • I flag di validità vengono recuperati dall'API Address Validation quando un singolo cliente esegue l'accesso.

Cache per uso in produzione

Quando utilizzi l'API Address Validation, spesso vuoi memorizzare nella cache parte della risposta della chiamata 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 High Volume Address Validation, la memorizzazione nella cache dei dati deve seguire i Termini specifici dei servizi dell'API Address Validation, descritti nella Sezione 11.3. In base a queste informazioni, sarai in grado di determinare se l'indirizzo di un utente può non essere valido, nel qual caso chiederai all'utente un indirizzo corretto alla sua successiva interazione con l'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 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 dalla risposta. Tuttavia, in uno scenario headless, un utente non può fornire il consenso poiché la convalida dell'indirizzo avviene dal backend. Di conseguenza, 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 Verdetto è true,
  • Il validationGranularity nell'oggetto Esito è PREMISE o SUB_PREMISE
  • Nessun elemento AddressComponent contrassegnato come:
    • Inferred(nota: inferred=trueche si verifica 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 sopra riportati, è probabile che l'indirizzo di input sia di scarsa qualità e puoi memorizzare nella cache i flag nel database in modo che riflettano questo problema. I flag memorizzati nella cache indicano che l'indirizzo nel suo complesso è di scarsa qualità, mentre flag più dettagliati come Correttore ortografico 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 un prompt dell'interfaccia utente. Dopo che il cliente accetta l'indirizzo formattato, puoi memorizzare nella cache i seguenti elementi della risposta:

  • formattedAddress
  • postalAddress
  • addressComponent componentNames o
  • UspsData standardizedAddress

Implementare una convalida degli indirizzi headless

In base alla discussione sopra riportata:

  • Spesso è necessario memorizzare nella cache parte delle risposte 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 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 a volume elevato 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 migliorare una pipeline di dati con una logica di convalida degli indirizzi di volume elevato.

alt_text

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

  • 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 un feedback secondo cui alcuni indirizzi nel set di dati di input potrebbero non essere di alta qualità. Nel passaggio successivo, prenderemo questi indirizzi segnalati, li presenteremo all'utente e riceveremo il suo consenso per correggere l'indirizzo memorizzato.

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

alt_text

  1. Quando l'utente esegue l'accesso, verifica innanzitutto di aver memorizzato nella cache eventuali flag di convalida nel 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 all'utente l'indirizzo corretto per confermare.
  4. Se l'indirizzo è di buona qualità, l'API Address Validation restituisce un formattedAddress.
  5. Puoi presentare tale 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

High Volume Address Validation è un caso d'uso comune che probabilmente incontrerai 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 anche scritto un'implementazione di riferimento di Convalida degli indirizzi ad alto volume come libreria open source su GitHub. Dai un'occhiata per iniziare a creare rapidamente con High Volume Address Validation. Leggi anche l'articolo sui pattern di progettazione per usare la libreria in diversi scenari.

Passaggi successivi

Scarica il white paper Migliora pagamento, consegna e operazioni con indirizzi affidabili e guarda il webinar Migliorare l'acquisto, la consegna e le operazioni con Address Validation .

Ulteriori letture suggerite:

Collaboratori

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

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