Guida alla soluzione di convalida degli indirizzi

Diagramma di flusso che mostra la panoramica generale dei passaggi di test.

Obiettivo

La convalida degli indirizzi offre valore per una serie di casi d'uso e oltre alla qualità non elaborata dei risultati dei test, ti consigliamo di prendere in considerazione alcuni aspetti chiave. Ad esempio, una visione olistica dei prodotti compatibili in un flusso utente, come Completamento automatico dei luoghi e Maps, la disponibilità a livello di regione e l'affidabilità e la sicurezza per le aziende.

Quando arrivi al punto di valutare l'API Address Validation, ecco alcune linee guida che ti consigliamo di utilizzare durante i test.

Gli obiettivi di questo test sono:

  1. Verifica che l'API Address Validation sia adatta al tuo caso d'uso.
  2. Verifica in che modo l'API Address Validation soddisfa i requisiti delle tue soluzioni, ad esempio:
    • Identificazione di indirizzi di buona qualità.
    • Avvisare per risolvere i problemi relativi agli input di scarsa qualità.
    • Applicare correzioni ai dati dell'indirizzo, tra cui deduzioni, sostituzioni e correzioni ortografica.
    • Fornire un indirizzo di spedizione formattato.
    • Avvisi relativi a dati mancanti o errati delle strutture secondarie (solo Stati Uniti).
  3. Assicurati di ricevere un vantaggio misurabile dall'implementazione dell'API.

Dopo aver eseguito il test, potrai rispondere alle domande precedenti e determinare se l'API è adatta alla tua attività.

Preparare i dati

Il test deve essere eseguito su un campione dei dati sugli indirizzi esistenti. Non scegliere manualmente i dati per il test, ma scegli campioni casuali rappresentativi delle aree geografiche in cui operi. Ciò significa che, se operi sia negli Stati Uniti che nel Regno Unito, ma il 70% della tua attività viene svolto nel Regno Unito rispetto al 30% negli Stati Uniti, il campione deve riflettere questa suddivisione.

Utilizza gli indirizzi del punto di acquisizione. Ad esempio, se prevedi di implementare la convalida dell'indirizzo durante il pagamento in un sito di e-commerce, utilizza gli indirizzi inseriti dai clienti nel modulo prima di qualsiasi elaborazione esistente che potrebbe essere sostituita dall'implementazione dell'API Address Validation.

Prepara un campione di circa 5000-10000 record per il test.

Chiama l'API

Prerequisito della sezione: scopri come inviare una richiesta di convalida dell'indirizzo.

Una volta preparati i dati, dovrai eseguire ogni record di indirizzo in base all'API.

Per indicazioni su come chiamare l'API, consulta la documentazione dell'API Address Validation. Abbiamo anche un articolo che descrive le best practice per l'utilizzo dell'API Address Validation per elaborare indirizzi ad alto volume.

Il risultato di questo passaggio dovrebbe essere l'output dei dati dall'API per ogni record di indirizzo. Potrai quindi analizzare i risultati per determinare l'idoneità dell'API per il tuo caso d'uso. Puoi utilizzare un foglio di lavoro, un database o un altro strumento.

Esaminare i risultati

Prerequisito della sezione: scopri come gestire la risposta di convalida, in particolare il concetto di correzione, conferma e accettazione.

In questa sezione illustreremo gli scenari di output che puoi analizzare per valutare l'idoneità della soluzione.

Panoramica dei campi API principali discussi in questo documento

Dati di risposta

Che cos'è?

Come valutare

A cosa serve?

verdict.inputGranularity

Descrive la granularità dell'input dell'indirizzo.

SUB_PREMISE

PREMISE

PREMISE_PROXIMITY

BLOCCA

ROUTE

ALTRO

Consente di determinare se l'indirizzo inserito contiene dati sufficienti per essere potenzialmente valido.

verdict.validationGranularity

Descrive la convalida dell'output complessivo dell'indirizzo.

SUB_PREMISE

PREMISE

PREMISE_PROXIMITY

BLOCCA

ROUTE

ALTRO

Consente di determinare la qualità complessiva degli indirizzi in uscita dall'API.

verdict.hasInferredComponents

Indica se l'API ha dedotto un componente.

Vero/Falso

L'API è in grado di aggiungere componenti mancanti se può dedurre i dati. Ad esempio, un codice stato mancante.

verdict.hasReplacedComponents

Indica se l'API ha sostituito un componente.

Vero/Falso

L'API è in grado di sostituire i componenti errati con i dati corretti in alcuni scenari.

verdict.addressComplete

Indica se l'indirizzo è completo.

Vero/Falso

Se l'API determina che l'indirizzo di output contiene tutti i componenti necessari, il valore sarà True.

address.missingComponentTypes

Segnale di avviso se nell'indirizzo mancano componenti.

Per i valori, consulta la tabella 2.

Evidenzia i componenti mancanti di un indirizzo incompleto.

Esamina gli indirizzi validi

Ordina i dati restituiti dall'API per determinare l'insieme di indirizzi che il sistema accetterà come validi. Gli indicatori principali da cercare nell'API sono:

  • verdict.validationGranularity contiene PREMISE o una versione migliore.
  • verdict.addressComplete è true.
  • Nessun componente dedotto o sostituito.

Per ulteriori informazioni, vedi Accettare un indirizzo.

L'output di questo esercizio dovrebbe essere un sottoinsieme dei dati sugli indirizzi che verrebbero accettati come validi dal tuo sistema. A questo punto, puoi determinare:

  • La percentuale di accettazione è accettabile?
  • Se utilizzi un flusso di lavoro di convalida degli indirizzi esistente, il tasso di accettazione è equivalente o migliore?

Esempio: indirizzo valido

Indirizzo inserito

Regione

76 Buckingham Palace Road, London SW1W 9TQ

Regno Unito

Verdetto

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "addressComplete": true
}

Controllare gli indirizzi non validi

Questo passaggio è un'opportunità per esaminare manualmente alcuni dei dati dell'indirizzo contrassegnati come non validi e verificare se, senza l'utilizzo dell'API Address Validation, l'indirizzo non valido potrebbe causare problemi a valle.

Ordina i dati restituiti dall'API per determinare l'insieme di indirizzi che il tuo sistema contrassegnerà come non validi. Gli indicatori principali da cercare nell'API sono:

  • verdict.validationGranularity impostato su OTHER o ROUTE a seconda del livello di rischio.
  • verdict.addressComplete è false.

Per ulteriori informazioni, consulta la sezione Correggere un indirizzo.

L'output di questo esercizio dovrebbe essere un sottoinsieme dei dati sugli indirizzi che verrebbero contrassegnati come non validi dal sistema. A questo punto, puoi stabilire se la percentuale non valida è accettabile.

È importante notare che il contrassegno degli indirizzi come non validi è una funzionalità di base dell'API Address Validation e un tasso elevato di indirizzi contrassegnati come non validi non riflette necessariamente negativamente sull'API. L'API ti fornisce informazioni che indicano che c'è un problema con l'indirizzo e questo potrebbe portare a un aumento dell'efficienza del tuo flusso di lavoro rilevando gli errori in anticipo, prima che causino problemi a valle.

Esempio: indirizzo non valido

Indirizzo inserito

Regione

21 45 40th street

USA

Verdetto

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "OTHER",
  "geocodeGranularity": "OTHER",
  "hasUnconfirmedComponents": true
}

Controllare i componenti mancanti o non confermati

In questa fase, è possibile esaminare anche i componenti mancanti o non confermati. Fa parte dell'oggetto Address nel reso. I due campi sono missingComponentTypes e unconfirmedComponentTypes.

Utilizza questi campi per rilevare il motivo per cui un indirizzo è contrassegnato come non valido dall'API e raccogliere le informazioni corrette per l'indirizzo che lo rende valido, inviando al punto di raccolta dei dati i campi specifici errati. In questo modo, l'API offre valore fornendoti informazioni specifiche sulla qualità dei tuoi dati.

Esempio: componente mancante e non confermato

Indirizzo inserito

Regione

Fake St, New York, NY 10011

USA

Verdetto

{
     "inputGranularity": "ROUTE",
     "validationGranularity": "OTHER",
     "geocodeGranularity": "OTHER",
     "hasUnconfirmedComponents": true
}

Componenti mancanti e non confermati

"missingComponentTypes": [
    "street_number"
],
"unconfirmedComponentTypes": [
    "route"
]

Rivedi gli indirizzi con correzioni

L'API Address Validation è in grado di apportare correzioni ai dati di input, acquisendo un indirizzo potenzialmente non valido e producendo dati di indirizzo validi. Questo è uno dei modi in cui l'API aggiunge valore ed è importante rilevarlo nell'ambito del test.

Gli indicatori principali da cercare sono:

  • inferred, replaced o spellCorrected impostato su true su uno dei addressComponents.
  • verdict.hasInferredComponents o verdict.hasReplacedComponents impostato su true.

Per ulteriori informazioni, consulta la sezione Confermare un indirizzo.

L'output di questo esercizio dovrebbe essere un sottoinsieme dei dati degli indirizzi a cui è stata applicata una correzione dall'API.

Una parte di questi dati può essere esaminata manualmente per determinare se l'API apporta correzioni ai dati che ridurrebbero le difficoltà nel flusso di lavoro a valle.

Esempio: indirizzo con una correzione

Indirizzo inserito

Regione

76 Bruckingm Palace Road, Londra SW1W 9TQ

Regno Unito

Percorso addressComponent

{
    "componentName": {
        "text": "Buckingham Palace Road",
        "languageCode": "en"
    },
    "componentType": "route",
    "confirmationLevel": "CONFIRMED",
    "spellCorrected": true
}

[Solo Stati Uniti] Controllare l'indirizzo con dati mancanti o errati relativi alle pertinenze

L'API Address Validation è in grado di determinare se un'unità secondaria è mancante o errata per gli indirizzi statunitensi.

Gli indicatori principali da cercare sono:

  • Nell'oggetto Address:
    • unconfirmedComponentTypes contiene subpremise
    • missingComponentTypes contiene subpremise
  • Nell'oggetto UspsData:
    • dpvConfirmation è D (premessa secondaria mancante)
    • dpvConfirmation è S (subpremise non confermato)

Per ulteriori informazioni, consulta la sezione Gestire gli indirizzi degli Stati Uniti.

Questo test indica se nei dati sono presenti problemi relativi a unità secondarie mancanti o scorrette, ad esempio i numeri degli appartamenti. Ciò può causare problemi a valle, in particolare per i casi d'uso di pubblicazione. L'API Address Validation può aggiungere valore al tuo flusso di lavoro identificando questo problema in precedenza, consentendoti di implementare passaggi per raccogliere i dati corretti.

Esempio: proprietà secondaria mancante

Indirizzo inserito

Regione

111 8th Avenue, Manhattan, NY 10011

US

Componente mancante

"missingComponentTypes": [
    "subpremise"
]

Conferma della DPV dei dati USPS

"dpvConfirmation": "D"

[Solo Stati Uniti] Controllare l'attributo standardizedAddress di USPS

L'API Address Validation restituisce anche l'indirizzo standardizzato USPS per gli indirizzi degli Stati Uniti. Questo è particolarmente importante se richiedi che gli indirizzi formattati per USPS vengano stampati sulle etichette di spedizione.

Puoi esaminare UspsAddress per visualizzare questi dati e determinare se aggiunge valore al tuo flusso di lavoro.

Esempio: indirizzo standardizzato USPS

"standardizedAddress": {
    "firstAddressLine": "111 8TH AVE FL 11",
    "cityStateZipAddressLine": "NEW YORK NY 10011-5201",
    "city": "NEW YORK",
    "state": "NY",
    "zipCode": "10011",
    "zipCodeExtension": "5201"
}

Conclusione

Inizia i test: inizia oggi stesso i test dell'API Address Validation per garantire dati sugli indirizzi accurati, migliorare la customer experience e semplificare le operazioni della tua attività. Dopo aver seguito gli scenari di test descritti sopra, avrai le informazioni necessarie per determinare se l'API Address Validation apporterà valore al tuo flusso di lavoro.

Letture consigliate:

Collaboratori

Henrik Valve | DevX Engineer