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 un solo indirizzo alla volta. In questo documento, vedremo 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 vediamo 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. Gli indirizzi potrebbero essere presenti in un file con valori separati da virgole e vuoi verificarne 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 lavori pianificati per convalidare gli indirizzi per i dettagli acquisiti durante il giorno, ad esempio dalle registrazioni dei clienti, dai dettagli degli ordini e 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 in seguito durante l'aggiornamento nel sistema online. Vuoi verificare che gli indirizzi siano corretti durante l'inserimento 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 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.

Memorizzazione nella cache per l'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 tramite l'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. Grazie a queste informazioni potrai stabilire se l'indirizzo di un utente non è valido. In questo caso, all'utente verrà richiesto di fornire un indirizzo corretto alla successiva interazione con la richiesta di iscrizione.

• Dati dall'oggetto Verdict

  • inputGranularity
  • validationGranularity
  • geocodeGranularity
  • addressComplete
  • hasUnconfirmedComponents
  • hasInferredComponents
  • hasReplacedComponents

• 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. Ciò garantisce che l'utente sia ben consapevole del motivo per cui un determinato servizio sta memorizzando il suo indirizzo e che sia d'accordo con 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 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 di input sia di qualità trasparente:

• 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 il correttore ortografico, indicano il tipo specifico di problema relativo alla 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 tramite 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

Implementazione di una convalida di indirizzi headless

In base alla discussione sopra riportata:

• Per motivi aziendali è spesso necessario memorizzare nella cache una parte della risposta dall'API Address Validation.
• 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 fasi 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.

• In base ai Termini di servizio , puoi memorizzare nella cache addressComplete,validationGranularity and validationFlags durante la convalida degli indirizzi in modo headless .

• Puoi memorizzare nella cache addressComplete,validationGranularity and validationFlags, PlaceID in base a uno UserID specifico nel database del cliente.

Pertanto, durante questo passaggio dell'implementazione, memorizzeremo nella cache i campi sopra menzionati nello 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 e li presenteremo all'utente e chiederemo il suo consenso alla correzione dell'indirizzo memorizzato.

Diagramma B: questo diagramma mostra l'aspetto di un'integrazione end-to-end del flusso di consenso dell'utente:

1. Quando l'utente accede, verifica innanzitutto se hai memorizzato nella cache eventuali flag di convalida nel tuo sistema, ad esempio:

   • addressComplete è vero
   • validationGranularity non deve essere PREMISE o SUB_PREMISE
   • validationFlags è inferred,spellCorrected,replaced,unexpected.
     • Se non sono presenti flag, è molto probabile che l'indirizzo memorizzato nella cache esistente sia di buona qualità e che possa essere utilizzato.

2. Se sono presenti dei flag, devi presentare all'utente un'interfaccia utente per correggere/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 delle correzioni, oppure accettare in silenzio se non ci sono correzioni.

6. Una volta che l'utente accetta, puoi memorizzare nella cache formattedAddress nel database.

Pseudocodice di implementazione del Passaggio 2:

If addressComplete is FALSE

OR

If validationGranularity is Not PREMISE OR SUB_PREMISE

OR

If validationFlags is inferred OR spellCorrected OR replaced OR unexpected
  {

    # This means there are issues with the existing cached address

    Call UI to present the address to user

}
Else{

    # This means existing address is good
  Proceed to checkout
}

Conclusione

La convalida degli indirizzi per volumi elevati è un caso d’uso comune che probabilmente incontrerai 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 per l'utilizzo della libreria in scenari diversi.

Passaggi successivi

Scarica il white paper Migliorare la procedura di pagamento, la consegna e le operazioni con indirizzi affidabili e guardare il webinar Migliorare procedura di pagamento, consegna e operazioni con Address Validation .

Ulteriore lettura suggerita:

• Applicazioni di convalida degli indirizzi per volumi elevati
• Libreria Python su GitHub
• Esplora la demo di Address Validation

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