Crea la logica di convalida

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

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

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

Scopo principale

Questo documento ti aiuta a modificare il 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 le linee guida per l'implementazione . Puoi anche utilizzare la nostra implementazione open source di questa logica, che si trova nella libreria di componenti estesa.

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 controllare nella risposta. Gli indicatori descritti qui provengono dalla proprietà verdict e non sono gli unici indicatori da controllare, ma forniscono un indicatore iniziale della qualità dell'indirizzo. Ogni tipo di comportamento corrisponde a una sezione di questo documento che descrive altri indicatori che potresti dover esaminare.

Comportamento del sistema
Correggi l'indirizzo	La risposta di verdict indica informazioni importanti mancanti informazioni che devono essere fornite. La qualità dell'indirizzo restituito dall'API potrebbe non essere sufficiente per la consegna. Flusso di lavoro Esamina i componenti dell'indirizzo, se necessario. Chiedi al cliente di correggere i problemi relativi all'indirizzo. Richiedi la convalida dell'indirizzo aggiornato. Procedi con l'indirizzo. Indicatori di esito Si applica uno qualsiasi dei seguenti: validationGranularity è impostato su OTHER. addressComplete è false.
Conferma l'indirizzo	La risposta di verdict indica un indirizzo consegnabile ma sono state apportate modifiche all'input originale: inferenza dei dati con correzione ortografica o dati che possono essere confermati. Flusso di lavoro Correzioni necessarie: Esamina i componenti dell'indirizzo, se necessario. Richiedi la convalida dell'indirizzo aggiornato. Procedi con l'indirizzo. Nessuna correzione necessaria: Procedi con l'indirizzo. Indicatori di esito Si applicano tutti i seguenti: validationGranularity contiene ROUTE addressComplete è true. hasInferredComponents campo è true OPPURE hasReplacedComponents campo è true.
Accetta l'indirizzo	La risposta dell'API Address Validation indica un indirizzo di qualità eccellente. Flusso di lavoro Procedi con l'indirizzo restituito. Indicatori di esito Si applicano tutti i seguenti: validationGranularity contiene PREMISE o un valore migliore. addressComplete è true. Nessun componente inferito o sostituito.

Linee guida per l'implementazione

Quando progetti la risposta del sistema agli indicatori di convalida dell'indirizzo, i seguenti consigli possono aiutarti a creare un modello di risposta più efficace. Tuttavia, si tratta solo di 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 bilanci la richiesta di correzioni e l'accettazione dell'indirizzo così come è stato inserito.	L'API Address Validation restituisce una serie di indicatori che puoi incorporare con il tuo livello di rischio per ottimizzare la procedura di convalida Ad esempio, se un indirizzo ha un numero civico non confermato, puoi comunque accettarlo. D'altra parte, se la tua attività richiede una maggiore precisione dell'indirizzo, potresti chiedere all'utente. Per un esempio che potrebbe rientrare in entrambe le categorie, vedi Numero civico non confermato non statunitense in Accetta indirizzo - esempi.
Accetta indirizzi	È una buona pratica consentire al sistema di accettare l'inserimento originale se il cliente non risponde alle richieste.	In questi casi, il cliente potrebbe aver inserito un indirizzo non presente nel sistema, ad esempio per una nuova costruzione.

Prova la demo. Il resto di questo documento utilizza una serie di esempi per aiutarti a comprendere la procedura di correzione, conferma e accettazione descritta 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 è consegnabile. Il sistema può quindi chiedere al cliente di fornire le informazioni necessarie, dopodiché puoi riemettere il flusso di lavoro per ottenere un indirizzo consegnabile.

Indicatori di correzione

L'API Address Validation fornisce una serie di indicatori per indicare 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 validationGranularity campo è OTHER, il sistema deve esaminare gli indicatori dei componenti dell'indirizzo per scoprire di più su dove si è verificato l'errore e su come correggerlo.
• Ogni volta che l'oggetto address post-elaborato restituisce un campo missingComponentTypes, il sistema deve verificare la presenza di questo componente. I componenti mancanti rendono anche un indirizzo incompleto e non consegnabile.

2. Altri indicatori

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

Componenti sospetti	Quando l'enumerazione del livello di conferma per 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 indirizzo statunitense

Alcuni campi applicabili solo agli indirizzi statunitensi forniscono un indicatore utile che l'indirizzo non è consegnabile e deve essere corretto. Per un indirizzo che richiede una correzione, dovresti visualizzare quanto segue:

dpvConfirmation	N, D o vuoto.

Per i dettagli su dpvConfirmation, vedi Gestire gli indirizzi statunitensi.

Esempi di correzione degli indirizzi

Confermare un indirizzo

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

Per fornire al cliente la richiesta corretta, la tua logica identificherà i componenti contrassegnati dal servizio per determinare quale azione o indicatore l'API ha applicato al componente, ad esempio inferred, replaced o spellCorrected. Consulta AddressComponent nei riferimenti.

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

Indicatori di conferma

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

1. Granularità della convalida

Un validationGranularity di ROUTE o superiore è accettabile, ma PREMISE o SUBPREMISE fornisce un indicatore più forte di consegnabilità.

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 inferiti	Quando il hasInferredComponents campo è true, sai che l'API ha compilato le informazioni ricavate da altri componenti dell'indirizzo.
Dati sostituiti	Quando il hasReplacedComponents campo è true, l' API ha sostituito i dati inseriti con i dati che riteneva validi per l'indirizzo.

3. Indicatori di indirizzo statunitense

Alcuni campi applicabili solo agli indirizzi statunitensi indicano che la tua logica deve confermare i dettagli con il cliente. Si applica una delle seguenti opzioni:

dpvConfirmation	S Per i dettagli su dpvConfirmation, vedi Gestire gli indirizzi statunitensi.
Risposta dell'indirizzo	Contiene il campo missingComponentTypes con il valore di subpremise. Nota: se il campo contiene tipi diversi da subpremise, l'azione rientra nella categoria di correzione dell'indirizzo. Consulta l'elenco completo dei tipi di indirizzi nella documentazione di Geocoding.

Esempi di conferma degli indirizzi

Accettare un indirizzo

Accetta un indirizzo quando l'esito fornisce un elevato grado di certezza che l'indirizzo è consegnabile e può essere utilizzato senza ulteriori interazioni con il cliente nella procedura downstream.

Indicatori di accettazione

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

1. Granularità della convalida

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

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 inferito. In questo caso, hasInferredComponents: FALSE.

3. Indicatori di indirizzo statunitense

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

dpvConfirmation	Y Per i dettagli su dpvConfirmation, vedi Gestire gli indirizzi statunitensi.

Esempi di accettazione degli indirizzi