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 diversi casi è 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, dai dettagli degli ordini, 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 indirizzi di un database dei 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. 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 base 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 o a un altro ID principale dell'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 dell'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 della condivisione.

Un esempio di consenso dell'utente è l'interazione diretta con un modulo di indirizzo di un sito di e-commerce in una pagina di pagamento. È inteso che memorizzerai nella cache e tratterai 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.

Interpreta la risposta

Se la risposta dell'API Address Validation contiene i seguenti indicatori, puoi essere certo che l'indirizzo inserito è di qualità idonea alla consegna:

  • L'indicatore addressComplete nell'oggetto Verdict è true,
  • 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 di convalida dell'indirizzo 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 componentNameso
  • 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 seguente, illustreremo una procedura in due passaggi per conformarsi ai 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 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.

alt_text

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

  • confirmationLevel
  • inferred
  • spellCorrected
  • replaced
  • unexpected

Pertanto, durante questo passaggio dell'implementazione, memorizzeremo nella cache i campi sopra menzionati in base all'User-ID.

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

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:

alt_text

  1. Quando l'utente accede, controlla innanzitutto se hai memorizzato nella cache eventuali indicatori di convalida nel tuo sistema.
  2. Se sono presenti segnalazioni, 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 valore formattedAddress.
  5. Puoi presentare l'indirizzo all'utente se sono state apportate correzioni oppure accettarlo silenziosamente se non sono state apportate correzioni.
  6. Una volta che l'utente accetta, puoi memorizzare nella cache il valore 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. Consulta anche l'articolo sui pattern di progettazione su come utilizzare 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:

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