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, viene elaborato un solo indirizzo alla volta. In questo documento, esamineremo come utilizzare la convalida indirizzo ad alto volume in scenari diversi, dai test dell'API alla convalida di indirizzi una tantum e ricorrente.

casi d'uso

Ora vedremo i casi d'uso in cui la convalida degli indirizzi per volumi elevati è utile.

Test

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

Convalida una tantum degli indirizzi

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

Convalida ricorrente degli indirizzi

La convalida degli indirizzi su base ricorrente prevede una serie di scenari:

  • Potresti avere job pianificati per convalidare gli indirizzi per i dettagli acquisiti durante la giornata, ad esempio dalle registrazioni dei clienti, dai dettagli degli ordini, dalle pianificazioni 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 dell'uso.
  • Potresti raccogliere indirizzi durante sondaggi o varie promozioni e successivamente in seguito all'aggiornamento nel sistema online. Vorresti verificare 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 dei clienti (ovvero un database con i dettagli del cliente)
  • Puoi memorizzare nella cache i flag di validità rispetto ai singoli indirizzi del 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 una 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 di un account utente. Ciò significa che nel database, i metadati 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 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 non è valido, nel qual caso dovrai chiedere all'utente un indirizzo corretto alla sua successiva interazione con la tua applicazione.

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

Se vuoi memorizzare nella cache informazioni sull'indirizzo effettivo, i dati devono essere memorizzati nella cache solo con il consenso dell'utente. Ciò garantisce che l'utente sia consapevole del motivo per cui un determinato servizio sta memorizzando il suo indirizzo e che accetti i termini di condivisione del suo indirizzo.

Un esempio di consenso dell'utente è l'interazione diretta con un modulo per l'indirizzo e-commerce su una pagina di pagamento. Si è certi che dovrai memorizzare nella cache ed elaborare l'indirizzo 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. 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 marcatori, puoi avere la certezza che l'indirizzo di input sia di qualità idoneo:

  • L'indicatore addressComplete nell'oggetto Verdetto è true,
  • validationGranularity nell'oggetto Verdetto è PREMISE o SUB_PREMISE
  • Nessuno degli 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 sopra riportati, è probabile che l'indirizzo di input fosse di scarsa qualità, pertanto puoi memorizzare nella cache i flag nel tuo database per riflettere questo fatto. I flag memorizzati nella cache indicano che l'indirizzo nel suo complesso è di scarsa qualità, mentre i flag più dettagliati, come Correttore ortografico, 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 dell'interfaccia utente. Una volta che il cliente accetta l'indirizzo formattato, puoi memorizzare nella cache quanto segue:

  • formattedAddress
  • postalAddress
  • addressComponent componentNames o
  • UspsData standardizedAddress

Implementare una convalida di indirizzi headless

In base alla discussione sopra riportata:

  • 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, illustreremo una procedura in due passaggi su come conformarsi ai Termini di servizio e implementare la convalida degli indirizzi per volumi elevati.

Passaggio 1:

Nel primo passaggio, vedremo come implementare uno script di convalida degli indirizzi per volumi elevati 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 High Volume Address Validation.

alt_text

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

  • confirmationLevel
  • inferred
  • spellCorrected
  • replaced
  • unexpected

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

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

Passaggio 2:

Nel passaggio 1, abbiamo raccolto il 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 presenteremo all'utente e chiederemo il suo consenso alla correzione dell'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 flag di convalida nel tuo sistema.
  2. Se sono presenti dei flag, devi presentare all'utente una UI per correggere e aggiornare l'indirizzo.
  3. Puoi chiamare di nuovo l'API Address Validation con l'indirizzo aggiornato o memorizzato nella cache e presentare all'utente l'indirizzo corretto per confermarlo.
  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 in silenzio se non ci sono correzioni.
  6. Una volta che l'utente accetta, puoi memorizzare nella cache formattedAddress nel database.

Conclusione

La convalida degli indirizzi per volumi elevati è un caso d'uso comune che potresti incontrare in molte applicazioni. Questo documento tenta di dimostrare alcuni scenari e un modello 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 High Volume Address Validation 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 dell'uso della libreria in scenari diversi.

Passaggi successivi

Scarica il white paper, ovvero il miglioramento di checkout, consegna e operazioni con indirizzi affidabili, e visualizza il webinar Migliorare procedura di pagamento, consegna e operazioni con Address Validation .

Ulteriore lettura suggerita:

Collaboratori

Google gestisce questo articolo. I seguenti collaboratori lo hanno scritto in origine.
Autori principali:

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