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 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. 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. Vedi 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: Esamina i componenti dell'indirizzo, se necessario. 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. Vedi Gestire gli indirizzi aggiornati. Procedi con l'indirizzo. Indicatori di verdetto Si applicano tutte le seguenti condizioni: validationGranularity contiene ROUTE o una versione successiva. 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 di reso. Indicatori di verdetto Si applicano tutte le seguenti condizioni: validationGranularity contiene PREMISE o migliore. Consulta 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 scegliere tra chiedere correzioni e accettare l'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 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 statunitense non confermato 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 per 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. 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 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é puoi riemettere il flusso di lavoro per ottenere un indirizzo di recapito.

Nota: quando ripeti richieste all'API Address Validation per lo stesso indirizzo, puoi effettuare una chiamata a provideValidationFeedback per indicare l'esito. 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 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-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 per gli indirizzi negli 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 deve essere corretto, 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 a cui è possibile consegnare, ma preferisci una maggiore sicurezza 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 per gli indirizzi negli 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 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 recapitabile.

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.

Esempi di indirizzi accettati