Crea la logica di convalida

Questo documento descrive una procedura per creare un sistema di controllo degli indirizzi per gestire una serie di risposte dall'API Address Validation. Spiega come creare la logica per utilizzare correttamente la risposta, per esaminare altri indicatori dell'API e quando e come chiedere ai clienti ulteriori informazioni.

In generale, la risposta dell'API determina i seguenti modi in cui il tuo sistema deve gestire un indirizzo:

• Correggi: l'indirizzo è di bassa qualità. Dovresti chiedere ulteriori informazioni.
• Conferma: l'indirizzo è di alta qualità, ma presenta modifiche rispetto all'indirizzo di input. Potresti chiedere una conferma.
• Accetta: l'indirizzo è di alta qualità. Puoi accettare l'indirizzo fornito.

Scopo principale

Questo documento ti aiuta a modificare il tuo sistema per analizzare al meglio la risposta dell'API e determinare le azioni successive da intraprendere con gli indirizzi forniti. Il seguente pseudocodice illustra un possibile flusso.

if (the API response indicates significant problems in the address)
    FIX - prompt the user to fix the address
else if (the API response indicates less significant problems in the address)
    CONFIRM - confirm with the user that the address is correct
else
    ACCEPT - continue with the address returned by the API.

La logica esatta dipende dalla tua situazione; per maggiori dettagli, consulta la guida all'implementazione. Puoi anche utilizzare la nostra implementazione open source di questa logica, che si trova nella Extended Component Library.

Panoramica del flusso di lavoro

La tabella seguente riassume due azioni per il tuo sistema:

1. Il flusso di lavoro da utilizzare in base al comportamento di correzione, conferma e accettazione.
2. I primi indicatori da verificare nella risposta. Gli indicatori descritti qui provengono dalla proprietà verdict e non sono gli unici indicatori da controllare, ma forniscono un'indicazione iniziale della qualità dell'indirizzo. Ogni tipo di comportamento corrisponde a una sezione di questo documento che descrive altri indicatori che potresti dover esaminare.

Il comportamento del tuo sistema
Correggi l'indirizzo	La risposta di verdict indica che mancano informazioni importanti che devono essere fornite. L'indirizzo restituito dall'API potrebbe non essere di qualità idonea alla consegna. Workflow Se necessario, esamina i componenti dell'indirizzo. Chiedi al cliente di risolvere i problemi relativi all'indirizzo. Richiedi la convalida per l'indirizzo aggiornato. Procedi con l'indirizzo. Indicatori di verdetto Uno dei seguenti casi: validationGranularity impostato su OTHER. addressComplete è false.
Conferma l'indirizzo	La risposta di verdict indica un indirizzo consegnabile, ma ha apportato modifiche all'input originale: deduzione di dati con ortografia corretta o dati che possono essere confermati. Workflow Correzioni necessarie: Se necessario, esamina i componenti dell'indirizzo. Richiedi la convalida dell'indirizzo aggiornato. Procedi con l'indirizzo. Nessuna correzione necessaria: Procedi con l'indirizzo. Indicatori di verdetto Si applicano tutte le seguenti condizioni: validationGranularity contiene ROUTE addressComplete è true. hasInferredComponents è true OPPURE hasReplacedComponents è true.
Accetta l'indirizzo	La risposta dell'API Address Validation indica un indirizzo di qualità eccellente. Workflow Procedi con l'indirizzo restituito. Indicatori di verdetto Si applicano tutte le seguenti condizioni: validationGranularity contiene PREMISE o un valore superiore. addressComplete è true. Nessun componente dedotto o sostituito.

Linee guida per l'implementazione

Quando progetti il modo in cui il tuo sistema risponde agli indicatori di Address Validation, i seguenti consigli possono aiutarti a creare un modello di risposta più efficace. Tuttavia, questi sono solo consigli, quindi tieni presente che l'implementazione deve essere adatta al tuo modello di business.

	Consulenza	Dettagli
Livello di rischio	Tieni conto del livello di tolleranza per la tua situazione quando trovi un equilibrio tra la richiesta di correzioni e l'accettazione dell'indirizzo inserito.	L'API Address Validation restituisce una serie di indicatori che puoi incorporare con il tuo livello di rischio per ottimizzare il processo di convalida. Ad esempio, se un indirizzo ha un numero civico non confermato, puoi comunque accettarlo. D'altra parte, se le tue operazioni aziendali richiedono una maggiore precisione dell'indirizzo, potresti chiedere all'utente di fornirlo. Per un esempio che potrebbe rientrare in entrambe le categorie, consulta Numero civico non confermato al di fuori degli Stati Uniti in Accetta indirizzo - Esempi.
Accetta indirizzi	È buona norma consentire al sistema di accettare la voce originale se il cliente non risponde ai prompt.	In questi casi, il cliente potrebbe aver inserito un indirizzo non presente nel sistema, ad esempio per un nuovo edificio.

Prova la demo. Il resto di questo documento utilizza una serie di esempi per aiutarti a comprendere il processo del flusso di correzione, conferma e accettazione descritto sopra. Puoi esplorare i risultati di questi esempi inserendoli nella demo di Address Validation nell'API Maps JavaScript.

Correggere un indirizzo

Correggi un indirizzo quando i risultati indicano chiaramente che l'indirizzo non è recapitabile. Il tuo sistema può quindi chiedere al cliente di fornire le informazioni necessarie, dopodiché puoi riemettere il workflow per ottenere un indirizzo di consegna.

Correggi gli indicatori

L'API Address Validation fornisce una serie di indicatori per farti sapere se un indirizzo deve essere corretto.

1. Granularità della convalida e componenti mancanti

Questi due indicatori forniscono la migliore indicazione di un indirizzo problematico:

• Ogni volta che il campo validationGranularity è OTHER, il tuo sistema deve esaminare gli indicatori dei componenti dell'indirizzo per scoprire di più su dove si è verificata l'occorrenza e su come risolvere il problema.
• Ogni volta che l'oggetto address post-elaborato restituisce un campo missingComponentTypes, il tuo sistema deve verificare la presenza di quel componente. Anche i componenti mancanti rendono un indirizzo incompleto e non recapitabile.

2. Altri indicatori

L'API Address Validation fornisce anche altri indicatori per aiutare a diagnosticare problemi specifici:

Componenti sospetti	Quando l'enum del livello di conferma di un componente è UNCOMFIRMED_AND_SUSPICIOUS, è probabile che il componente non sia corretto.
Componente non risolto	Un unresolvedToken è una parte dell'input non riconosciuta come parte valida di un indirizzo.

3. Indicatori di indirizzi negli Stati Uniti

Alcuni campi applicabili solo agli indirizzi degli Stati Uniti forniscono un indicatore utile del fatto che l'indirizzo non è recapitabile e deve essere corretto. Per un indirizzo che deve essere corretto, dovresti vedere quanto segue:

dpvConfirmation	N, D o vuoto.

Per maggiori dettagli su dpvConfirmation, consulta Gestisci gli indirizzi degli Stati Uniti.

Esempi di correzione degli indirizzi

Conferma un indirizzo

Confermi un indirizzo quando l'esito indica che l'API Address Validation ha dedotto o apportato modifiche ai componenti dell'indirizzo per produrre un indirizzo convalidato. In questi casi, hai un indirizzo recapitabile, ma preferisci avere una maggiore certezza che l'indirizzo risultante sia quello previsto dal cliente.

Per fornire al cliente il prompt corretto, la tua logica deve identificare i componenti segnalati dal servizio per determinare quale azione o flag l'API ha applicato al componente, ad esempio inferred, replaced o spellCorrected. Consulta AddressComponent nel riferimento.

Nota: considera il tuo livello di rischio quando decidi se confermare l'indirizzo con il cliente o accettarlo come valido.

Conferma gli indicatori

L'API Address Validation fornisce una serie di indicatori per farti sapere se un indirizzo deve essere confermato.

1. Granularità della convalida

Un validationGranularity di ROUTE o superiore è accettabile, ma PREMISE o SUBPREMISE forniscono un segnale più forte di recapitabilità.

2. Altri indicatori

Quando decidi di confermare l'inserimento dell'indirizzo con il cliente, l'esito fornisce anche quanto segue per determinare quali componenti esaminare:

Dati dedotti	Quando il campo hasInferredComponents è true, significa che l'API ha inserito le informazioni ricavate da altri componenti dell'indirizzo.
Dati sostituiti	Quando il campo hasReplacedComponents è true, l'API ha sostituito i dati inseriti con dati che ritiene validi per l'indirizzo.

3. Indicatori di indirizzi negli Stati Uniti

Alcuni campi applicabili solo agli indirizzi degli Stati Uniti indicano che la logica deve confermare i dettagli con il cliente. Si applica una delle seguenti condizioni:

dpvConfirmation	S Per maggiori dettagli su dpvConfirmation, consulta Gestisci gli indirizzi degli Stati Uniti.
Risposta all'indirizzo	Contiene il campo missingComponentTypes con il valore subpremise. Nota: se il campo contiene tipi diversi da subpremise, l'azione rientra nella categoria Correggi indirizzo. Consulta l'elenco completo dei tipi di indirizzi nella documentazione di Geocoding.

Esempi di conferma dell'indirizzo

Accetta un indirizzo

Accetti un indirizzo quando l'esito fornisce un elevato grado di certezza che l'indirizzo è recapitabile e può essere utilizzato senza ulteriori interazioni con il cliente nel processo downstream.

Accetta indicatori

L'API Address Validation fornisce una serie di indicatori per farti sapere se un indirizzo deve essere confermato.

1. Granularità della convalida

Un valore validationGranularity pari o superiore a PREMISE è accettabile, ma in alcuni casi ROUTE indica comunque un indirizzo di consegna.

2. Altri indicatori

Un esito per un indirizzo di alta qualità deve fornire anche quanto segue:

• Nessun dato sostituito. In questo caso, hasReplacedComponents: FALSE.
• Nessun componente dedotto. In questo caso, hasInferredComponents: FALSE.

3. Indicatori di indirizzi negli Stati Uniti

Alcuni campi applicabili solo agli indirizzi degli Stati Uniti indicano un indirizzo di alta qualità a cui è possibile effettuare la consegna. Per un indirizzo statunitense accettabile, dovresti vedere quanto segue:

dpvConfirmation	Y Per i dettagli su dpvConfirmation, consulta Gestisci gli indirizzi degli Stati Uniti.

Esempi di indirizzi accettati