Crea la tua logica di convalida

Questo documento descrive un processo per la creazione di un sistema di controllo degli indirizzi per 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 inserito. Potresti richiedere 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 eseguire con gli indirizzi forniti. Lo pseudocodice seguente 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 situazione. Per ulteriori dettagli, consulta le indicazioni sull'implementazione. Puoi anche utilizzare la nostra implementazione open source di questa logica, che si trova nella libreria dei componenti estesi.

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

Comportamento del sistema
Correggi l'indirizzo	La risposta da verdict indica importanti informazioni mancanti che devono essere fornite. L'indirizzo restituito dall'API Address Validation potrebbe non essere di qualità idoneo. Flusso di lavoro Esamina i componenti dell'indirizzo, se necessario. Chiedi al cliente di risolvere i problemi riscontrati. Richiedi la convalida dell'indirizzo aggiornato. (Facoltativo) Invia una richiesta all'endpoint di feedback per l'API. Vedi Gestire gli indirizzi aggiornati. Procedi con l'indirizzo. Indicatori del verdetto Si applica una delle seguenti condizioni: OTHER impostato per validationGranularity. Vedi i valori di granularità. addressComplete è false.
Conferma l'indirizzo	La risposta da verdict indica un indirizzo di consegna, ma ha apportato modifiche all'input originale: deduzione di dati corretti o dati che possono essere confermati. Flusso di lavoro Correzioni necessarie: Esamina i componenti dell'indirizzo, se necessario. Richiedi la convalida dell'indirizzo aggiornato. (Facoltativo) Invia una richiesta all'endpoint di feedback per l'API. Vedi Gestire gli indirizzi aggiornati. Procedi con l'indirizzo. Nessuna correzione necessaria: (Facoltativo) Invia una richiesta all'endpoint di feedback per l'API. Vedi Gestire gli indirizzi aggiornati. Procedi con l'indirizzo. Indicatori del verdetto Si applicano tutte le seguenti condizioni: validationGranularity contiene ROUTE o migliore. Vedi i valori di granularità. addressComplete è true. Il campo hasInferredComponents è true OPPURE il campo hasReplacedComponents è 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 del verdetto Si applicano tutte le seguenti condizioni: validationGranularity contiene PREMISE o migliore. Vedi i valori di granularità. addressComplete è true. Nessun componente dedotto o sostituito.

Linee guida per l'implementazione

Durante la progettazione del modo in cui il sistema risponde agli indicatori dell'API Address Validation, i seguenti suggerimenti possono aiutarti a creare un modello di risposta più efficace. Tuttavia, questi sono solo suggerimenti, quindi tieni presente che l'implementazione dovrebbe essere adatta al tuo modello di business.

	Consulenza	Dettagli
Livello di rischio	Tieni conto del livello di tolleranza per la tua situazione quando devi trovare 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. Se invece le operazioni aziendali richiedono una maggiore precisione degli indirizzi, potresti inviare una richiesta all'utente. Per un esempio che potrebbe rientrare in entrambe le categorie, consulta Numero civico non confermato negli Stati Uniti in Accettazione 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 un indirizzo di una nuova costruzione.
Invia il tuo feedback	Quando emetti di nuovo una richiesta di convalida degli indirizzi, puoi anche inviare una richiesta all'endpoint provideValidationFeedback.	In questo modo Google saprà come hai gestito la risposta finale. Vedi Gestire gli indirizzi aggiornati.

Prova la demo. Il resto di questo documento utilizza una serie di esempi per aiutarti a comprendere la procedura di correzione, conferma e accettazione del flusso descritta in precedenza. Puoi esplorare i risultati di questi esempi inserendoli nella demo dell'API Address Validation.

Correggere un indirizzo

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

Nota: quando ripeti richieste all'API Address Validation per lo stesso indirizzo, puoi effettuare una chiamata a provideValidationFeedback per indicare l'esito. Vedi Gestire gli indirizzi degli Stati Uniti.

Correggi indicatori

L'API Address Validation fornisce una serie di indicatori che ti comunicano se un indirizzo deve essere corretto.

1. Granularità della convalida e componenti mancanti

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

• Ogni volta che il campo validationGranularity è OTHER, il sistema deve esaminare gli indicatori dei componenti degli indirizzi per scoprire dove si è verificato l'errore e come correggerlo.
• Ogni volta che l'oggetto address post-elaborato restituisce un campo missingComponentTypes, il sistema deve verificare la presenza di quel componente. Inoltre, l'assenza di componenti rendono un indirizzo incompleto e non recapitabile.

2. Altri indicatori

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

Componenti sospetti	Quando l'enumerazione a 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 per gli indirizzi negli Stati Uniti

Alcuni campi applicabili solo agli indirizzi negli Stati Uniti forniscono un indicatore utile che l'indirizzo non è idoneo per la consegna 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, vedi Gestire gli indirizzi degli Stati Uniti.

Correggere esempi di 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 a cui è possibile consegnare, ma preferisci una maggiore sicurezza che l'indirizzo risultante sia quello previsto dal cliente.

Per fornire al cliente i prompt corretti, la logica identificherà i componenti segnalati dal servizio per determinare quale azione o segnalare l'API applicata al componente, ad esempio inferred, replaced o spellCorrected. Vedi AddressComponent nel riferimento.

Nota: valuta il tuo livello di rischio quando decidi se confermare l'indirizzo con il cliente o accettarlo come valido. Inoltre, nel caso in cui dovessi riemettere richieste all'API Address Validation, puoi effettuare una chiamata a provideValidationFeedback per indicare l'esito. Vedi Gestire gli indirizzi aggiornati.

Conferma indicatori

L'API Address Validation fornisce una serie di indicatori che ti informano se un indirizzo deve essere confermato.

1. Granularità della convalida

Un valore validationGranularity pari a ROUTE o superiore è accettabile, ma PREMISE o SUBPREMISE fornisce un segnale più forte della possibilità di recapito.

2. Altri indicatori

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

Dati dedotti	Se il campo hasInferredComponents è true, sai che l'API ha compilato le informazioni raccolte da altri componenti dell'indirizzo.
Dati sostituiti	Quando il campo hasReplacedComponents è true, l'API ha sostituito i dati inseriti con quelli che ritiene di rendere valido l'indirizzo.

3. Indicatori per gli indirizzi negli Stati Uniti

Alcuni campi applicabili solo agli indirizzi negli 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, vedi Gestire gli indirizzi degli Stati Uniti.
Risposta all'indirizzo	Contiene il campo missingComponentType con il valore subpremise. Nota: se il campo contiene tipi diversi da subpremise, l'azione rientrerebbe nella categoria di correzione dell'indirizzo. Consulta l'elenco completo dei tipi di indirizzi nella documentazione di Geocoding.

Esempi di verifica dell'indirizzo

Accetta un indirizzo

Accetti un indirizzo quando l'esito dimostra un elevato grado di certezza che l'indirizzo è idoneo e può essere utilizzato senza ulteriori interazioni del cliente nel processo downstream.

Accetta indicatori

L'API Address Validation fornisce una serie di indicatori che ti informano 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 di consegna.

2. Altri indicatori

Un esito relativo a un indirizzo di alta qualità dovrebbe anche fornire quanto segue:

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

3. Indicatori per gli indirizzi negli Stati Uniti

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

dpvConfirmation	Y Per maggiori dettagli su dpvConfirmation, vedi Gestire gli indirizzi degli Stati Uniti.

Accettare esempi di indirizzi