Crea la tua logica di convalida

Questo documento descrive un processo per creare 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 ulteriori informazioni ai tuoi clienti.

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

• Correzione: l'indirizzo è di bassa qualità. Dovresti chiedere maggiori informazioni.
• Conferma: l'indirizzo è di alta qualità, ma presenta modifiche rispetto all'indirizzo inserito. Potresti richiedere 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 situazione. Per ulteriori dettagli, consulta le linee guida per l'implementazione. Puoi anche utilizzare l'implementazione open source di questa logica, disponibile 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 alla correzione, conferma, accetta il comportamento.
2. I primi indicatori da verificare dalla risposta. Gli indicatori descritti qui provengono dalla proprietà verdict e sono non gli unici indicatori da verificare, 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 tuo 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à per l'invio. Flusso di lavoro Se necessario, esamina i componenti dell'indirizzo. Chiedi al cliente di risolvere i problemi relativi all'indirizzo. 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 qualsiasi delle seguenti condizioni: OTHER impostato per validationGranularity. Vedi i valori della granularità. addressComplete è false.
Conferma l'indirizzo	La risposta da verdict indica un indirizzo di consegna, ma ha apportato modifiche all'input originale: deducendo dati che sono stati corretti oppure che possono essere confermati. Flusso di lavoro Correzioni necessarie: Se necessario, esamina i componenti dell'indirizzo. 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 un valore superiore. Vedi i valori della 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 un valore superiore. Vedi i valori della granularità. addressComplete è true. Nessun componente dedotto o sostituito.

Linee guida per l'implementazione

Durante la progettazione del modo in cui il tuo sistema risponde agli indicatori dell'API Address Validation, i seguenti suggerimenti possono aiutarti a creare un modello di risposta più efficace. Tuttavia, si tratta solo di consigli, per cui l'implementazione deve essere adatta al tuo modello di business.

	Indicazioni	Dettagli
Livello di rischio	Tieni conto del livello di tolleranza per la tua situazione quando cerchi di trovare il giusto 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 degli indirizzi, potresti chiedere all'utente di farlo. Per un esempio che potrebbe rientrare in una delle due categorie, consulta la sezione Numero civico non confermato dagli Stati Uniti in Accetta indirizzo - esempi.
Accetta indirizzi	È buona norma consentire al sistema di accettare la voce originale se il cliente non risponde alle richieste.	In questi casi, il cliente potrebbe aver inserito un indirizzo non nel sistema, ad esempio per una nuova costruzione.
Fornire feedback	Quando emetti nuovamente una richiesta di convalida dell'indirizzo, puoi anche inviarne una all'endpoint provideValidationFeedback.	In questo modo, Google può sapere come hai gestito la risposta finale. Vedi Gestire gli indirizzi aggiornati.

Prova la demo. Il resto del 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 richiedere al cliente di fornire le informazioni necessarie, dopodiché potrai 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 il tuo risultato. Vedi Gestire gli indirizzi degli Stati Uniti.

Correggi gli indicatori

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

1. Granularità di convalida e componenti mancanti

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

• Ogni volta che il campo validationGranularity è OTHER, il sistema deve analizzare gli indicatori dei componenti dell'indirizzo per scoprire di più su dove si è verificato l'errore e su come risolverlo.
• Ogni volta che l'oggetto address post-elaborato restituisce un campo missingComponentTypes, il sistema deve verificare la presenza di tale componente. Inoltre, i componenti mancanti rendono un indirizzo incompleto e non recapitabile.

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 degli indirizzi statunitensi

Alcuni campi applicabili solo agli indirizzi negli Stati Uniti forniscono un indicatore utile del fatto che l'indirizzo non può essere recapitato 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 gli esempi di indirizzi

Conferma un indirizzo

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

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

Nota: considera il tuo livello di rischio quando decidi se confermare l'indirizzo con il cliente o accettarlo come valido. Inoltre, se dovresti 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 per farti sapere se un indirizzo deve essere confermato.

1. Granularità della convalida

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

2. Altri indicatori

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

Dati dedotti	Quando il campo hasInferredComponents è true, l'API ha compilato le informazioni che ha raccolto da altri componenti degli indirizzi.
Dati sostituiti	Quando il campo hasReplacedComponents è true, l'API ha sostituito i dati inseriti con dati ritenuti validi per l'indirizzo.

3. Indicatori degli indirizzi statunitensi

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.
Rispondere alla risposta	Contiene il campo missingComponentType con il valore subpremise. Nota: se il campo contiene tipi diversi da subpremise, l'azione rientra nella categoria di indirizzi corretti. Consulta l'elenco completo dei tipi di indirizzi nella documentazione di Geocoding.

Conferma esempi di indirizzi

Accetta un indirizzo

Accetti un indirizzo quando l'esito fornisce un elevato grado di certezza che l'indirizzo può essere fornito e può essere utilizzato senza ulteriore interazione con il cliente nel processo a valle.

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

L'esito di un indirizzo di alta qualità deve anche includere quanto segue:

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

3. Indicatori degli indirizzi statunitensi

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.

Accetta esempi di indirizzi