Informazioni su una risposta di convalida degli indirizzi di base

Nota :questo documento descrive gli elementi di base di una risposta di convalida dell'indirizzo per un indirizzo di alta qualità. Per indicazioni su come lavorare con scenari di indirizzi reali e creare logica intorno a risposte più complesse, consulta Crea la logica di convalida.

L'API Address Validation fornisce un corpo della risposta come oggetto JSON che contiene due proprietà di primo livello:

• result, un oggetto di tipo ValidationResult
• responseID

{
  "result": {
    // Validation verdict.
    "verdict": {},
    // Address details determined by the API.
    "address": {},
    // The geocode generated for the input address.
    "geocode": {},
    // Information indicating if the address is a business, residence, etc.
    "metadata": {},
    // Information about the address from the US Postal Service
    // ("US" and "PR" addresses only).
    "uspsData": {},
  },
  // A unique identifier generated for every request to the API.
  "responseId": "ID"
}

Questo documento si concentra sull'oggetto result. Per informazioni su responseID, vedi Gestire gli indirizzi aggiornati.

Proprietà verdict

Punto chiave: utilizza la proprietà verdict per ottenere un riepilogo di base della qualità dell'indirizzo.

La proprietà verdict riassume i risultati della convalida dell'indirizzo e deve essere la prima proprietà da valutare quando si crea la logica di controllo dell'indirizzo. La proprietà può restituire una serie di campi, a seconda della qualità dell'indirizzo di output. Ad esempio, di seguito viene mostrata la proprietà verdict di un indirizzo di buona qualità, che restituisce 4 campi per questa richiesta specifica:

"verdict": {
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "addressComplete": true,
  "possibleNextAction": "ACCEPT"
}

Le sezioni seguenti riepilogano tutti i campi della proprietà verdict.

Consulta la sezione Verdict

Possibile azione successiva

La proprietà possibleNextAction offre un riepilogo interpretativo del resto della risposta dell'API, con l'obiettivo di aiutarti a determinare se devi o meno chiedere al cliente di rivedere o apportare modifiche al suo indirizzo. Per maggiori dettagli, consulta la sezione Creare la logica di convalida.

Granularità dell'indirizzo

La granularità dell'indirizzo si riferisce al livello di dettaglio utilizzato per determinare la specificità di un indirizzo o di un geocodice. La specificità dell'indirizzo nella risposta validationGranularity è un indicatore chiave per stabilire se un indirizzo è raggiungibile.

La proprietà verdict restituisce i seguenti indicatori di granularità:

• inputGranularity: descrive il livello di dettaglio acquisito dall'indirizzo inviato all'API Address Validation. Il livello di dettaglio dell'indirizzo nella richiesta influisce sul livello di dettaglio dell'indirizzo nella risposta di convalida. Ad esempio, un indirizzo con un inputGranularity inferiore a PREMISE non comporta in genere un validationGranularity a un livello PREMISE.
• validationGranularity: il livello di granularità a cui l'API Address Validation può convalidare completamente l'indirizzo. Nella maggior parte dei casi, un livello di granularità pari a PREMISE o SUB_PREMISE indica un indirizzo di qualità che probabilmente è raggiungibile.
• geocodeGranularity: descrive il livello di dettaglio del geocodice associato all'indirizzo. Ad esempio, i record di Google potrebbero indicare l'esistenza di un numero di appartamento, ma non una posizione precisa per quell'appartamento specifico all'interno di un grande complesso residenziale. In questo caso, validationGranularity è SUB_PREMISE, ma geocodeGranularityisPREMISE`.

Consulta Granularità nella guida di riferimento.

Completezza dell'indirizzo

Il verdetto restituisce la proprietà addressComplete come indicatore di un indirizzo di alta qualità, il che significa in particolare che non presenta componenti mancanti, non risolti o imprevisti:

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "PREMISE",
    "geocodeGranularity": "PREMISE",
    "addressComplete": true,
    "possibleNextAction": "ACCEPT"
}

Quando l'indirizzo presenta componenti mancanti, non risolti o imprevisti, il campo è impostato su false.

Nota :quando la proprietà addressComplete non viene visualizzata nel verdetto dopo l'ispezione manuale, il suo valore è false. A seconda del linguaggio di programmazione, esegui una query sul verdetto per verificare la presenza della proprietà addressComplete o esegui una query direttamente sulla proprietà. Per un esempio, vedi Qualità dell'indirizzo di seguito.

Consulta addressComplete nelle sezioni Verdict e Indirizzo della guida di riferimento.

Qualità dell'indirizzo

Diversi campi possibili indicano problemi con i componenti dell'indirizzo o modifiche, ad esempio componenti dell'indirizzo dedotti o mancanti. Ad esempio, la seguente proprietà verdict indica un indirizzo con componenti non confermati e un campo addressComplete mancante:

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}

Consulta la sezione Verdict nella guida di riferimento.

Le proprietà address e addressComponent

Punto chiave: utilizza la proprietà address per ottenere la formattazione dell'indirizzo. Utilizza il relativo sottocomponente addressComponent per analizzare gli errori e fornire informazioni al riguardo ai tuoi clienti. Tuttavia, non creare l'integrazione in modo che si basi sul livello di conferma specifico per i componenti dell'indirizzo. Consulta la sezione Crea la logica di convalida per indicazioni sull'integrazione.

La proprietà address fornisce la formattazione dell'indirizzo elaborato fornito nella richiesta, insieme ai riepiloghi a livello di componente dell'indirizzo, incluse le parti dell'indirizzo con errori ortografici, le parti errate sostituite e le parti mancanti dedotte.

Consulta Address nella guida di riferimento.

La proprietà addressComponent è un sottocomponente di address che fornisce un elenco dettagliato degli elementi o dei componenti dell'indirizzo che l'API Address Validation ha elaborato. L'API identifica ogni campo del componente in base al nome, al tipo e al livello di conferma.

Consulta addressComponent nella guida di riferimento.

Proprietà geocode

Punto chiave: utilizza la proprietà geocode per ottenere comodamente il geocodice o l'ID luogo quando la logica chiamava in precedenza l'API Geocoding.

La proprietà geocode indica la posizione geocodificata associata all'indirizzo inserito. Questa proprietà fornisce dettagli sulla posizione stessa, ad esempio il relativo ID luogo.

Consulta Geocode nella guida di riferimento.

Proprietà metadata

Punto chiave: utilizza la proprietà metadata per determinare il tipo di proprietà associata all'indirizzo: residenziale, casella postale o attività.

Questa proprietà potrebbe non essere compilata per ogni indirizzo elaborato dall'API Address Validation, ma indica se l'indirizzo è di tipo residenziale, commerciale o una casella postale.

Consulta la copertura dell'API Address Validation e il riferimento per Address metadata.

Proprietà uspsData

Punto chiave: utilizza la proprietà uspsData per ottenere i livelli di confidenza della consegna e altri dettagli USPS sugli indirizzi statunitensi.

Questa proprietà fornisce informazioni utili per gli indirizzi postali degli Stati Uniti. Tuttavia, non è garantito che venga compilato completamente per ogni indirizzo convalidato dal servizio. Per questo motivo, non dovresti fare affidamento su questa proprietà come unico mezzo per convalidare gli indirizzi, ma controllare anche verdict e address.

Consulta Gestire gli indirizzi degli Stati Uniti e il riferimento per UspsData.