Crea la tua logica di convalida

Questo documento descrive la procedura per creare un sistema di controllo degli indirizzi per gestire una serie di risposte dell'API Address Validation. Spiega come sviluppare la logica per utilizzare correttamente la risposta, 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 sistema deve gestire un indirizzo:

• Correzione: l'indirizzo è di bassa qualità. Dovresti chiedere maggiori informazioni.
• Conferma: l'indirizzo è di alta qualità, ma presenta alcune differenze rispetto all'indirizzo inserito. Potresti dover confermare.
• 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 situazione. Per ulteriori dettagli, consulta le linee guida per l'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 sistema:

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

Il comportamento del sistema
Correggi l'indirizzo	La risposta del verdict indica informazioni importanti mancanti che devono essere fornite. L'indirizzo restituito dall'API Address Validation potrebbe non essere di qualità sufficiente per la consegna. 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. Consulta Gestire gli indirizzi aggiornati. Procedi con l'indirizzo. Indicatori di verdetto Si applica una delle seguenti condizioni: OTHER impostato per validationGranularity. Consulta i valori di granularità. addressComplete è false.
Conferma l'indirizzo	La risposta di verdict indica un indirizzo di destinazione, ma sono state apportate modifiche all'input originale: vengono dedotti i dati che sono stati corretti ortograficamente o 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. Consulta Gestire gli indirizzi aggiornati. Procedi con l'indirizzo. Nessuna correzione necessaria: (Facoltativo) Invia una richiesta all'endpoint di feedback per l'API. Consulta Gestire gli indirizzi aggiornati. Procedi con l'indirizzo. Indicatori di verdetto Si applicano tutti i seguenti requisiti: validationGranularity contiene ROUTE o una versione successiva. Consulta 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 ottima qualità. Flusso di lavoro Procedi con l'indirizzo di reso. Indicatori di verdetto Si applicano tutti i seguenti punti: validationGranularity contiene PREMISE o una versione successiva. Consulta i valori di granularità. addressComplete è true. Nessun componente dedotto o sostituito.

Linee guida per l'implementazione

Quando progetti la modalità di risposta del tuo sistema agli indicatori dell'API Address Validation, 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 devi scegliere tra chiedere correzioni e accettare l'indirizzo inserito.	L'API Address Validation restituisce una serie di indicatori che puoi incorporare nel tuo livello di rischio per ottimizzare il processo di convalida. Ad esempio, se un indirizzo non ha un numero civico confermato, puoi comunque accettarlo. D'altra parte, se la tua attività richiede una maggiore precisione dell'indirizzo, potresti chiedere all'utente di fornire ulteriori dettagli. Per un esempio che potrebbe rientrare in entrambe le categorie, consulta Numero civico non confermato al di fuori degli Stati Uniti in Indirizzo accettato - 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 una nuova costruzione.
Invia il tuo feedback	Quando emetti di nuovo una richiesta di convalida dell'indirizzo, puoi anche inviare una richiesta all'endpoint provideValidationFeedback.	In questo modo, Google saprà come hai gestito la risposta finale. Consulta 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 descritta sopra. 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 non è valido. Il sistema può quindi chiedere al cliente di fornire le informazioni necessarie, dopodiché puoi riemettere il flusso di lavoro per ottenere un indirizzo di recapito.

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

Correggere gli indicatori

L'API Address Validation fornisce una serie di indicatori per informarti 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 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-processato restituisce un campo missingComponentTypes, il 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 aiutarti a diagnosticare problemi specifici:

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

3. Indicatori di indirizzi degli Stati Uniti

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

dpvConfirmation	N, D o vuoto.

Per informazioni dettagliate su dpvConfirmation, consulta Gestire gli indirizzi degli Stati Uniti.

Esempi di indirizzi corretti

Conferma un indirizzo

Confermi un indirizzo quando il verdetto 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 di recapito, ma preferisci avere una maggiore certezza che l'indirizzo risultante sia quello previsto dal cliente.

Per fornire al cliente il prompt corretto, la logica identifica i componenti segnalati dal servizio per determinare quale azione o indicatore l'API ha applicato al componente, ad esempio inferred, replaced o spellCorrected. Consulta AddressComponent nella documentazione di riferimento.

Nota: tieni conto del livello di rischio quando decidi se confermare l'indirizzo con il cliente o accettarlo come valido. Inoltre, se emetti nuovamente richieste all'API Address Validation, puoi effettuare una chiamata a provideValidationFeedback per indicare il risultato. Consulta Gestire gli indirizzi aggiornati.

Conferma indicatori

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

1. Granularità della convalida

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

2. Altri indicatori

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

Dati dedotti	Quando il campo hasInferredComponents è true, sai 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 quelli ritenuti validi per l'indirizzo.

3. Indicatori di indirizzi degli Stati Uniti

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

dpvConfirmation	S Per informazioni dettagliate su dpvConfirmation, consulta 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 rientra nella categoria Correzione indirizzo. Consulta l'elenco completo dei tipi di indirizzi nella documentazione di Geocoding.

Esempi di indirizzi di conferma

Accettare un indirizzo

Accetti un indirizzo quando il verdetto fornisce un elevato grado di certezza che l'indirizzo sia recapitabile e possa essere utilizzato senza ulteriore interazione del cliente nel processo a valle.

Accettare gli indicatori

L'API Address Validation fornisce una serie di indicatori per informarti 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 recapitabile.

2. Altri indicatori

Un verdetto 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 degli Stati Uniti

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 vedere quanto segue:

dpvConfirmation	Y Per informazioni dettagliate su dpvConfirmation, consulta Gestire gli indirizzi degli Stati Uniti.

Esempi di indirizzi accettati