L'API Address Validation fornisce un corpo della risposta come oggetto JSON contenente due proprietà di primo livello:
result
, un oggetto di tipoValidationResult
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 è incentrato sull'oggetto result
. Per informazioni su responseID
, vedi Gestire gli indirizzi aggiornati.
La proprietà verdict
La proprietà verdict
riassume i risultati della convalida degli indirizzi e dovrebbe essere la prima proprietà da valutare durante la creazione della logica di controllo degli indirizzi.
La proprietà può restituire una varietà di campi, a seconda della qualità dell'indirizzo di output. Ad esempio, quanto segue mostra 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
}
Le seguenti sezioni riepilogano tutti i campi della proprietà verdict
.
Consulta il Esito nella guida di riferimento. |
Granularità dell'indirizzo
La granularità degli indirizzi si riferisce al livello di dettaglio utilizzato per determinare la specificità di un indirizzo o di un'area geografica. La specificità dell'indirizzo nella risposta validationGranularity
è un indicatore chiave per capire se un indirizzo può essere pubblicato o meno.
La proprietà verdict
restituisce questi 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 valoreinputGranularity
inferiore aPREMISE
in genere non genera un livello davalidationGranularity
aPREMISE
.validationGranularity
: il livello di granularità al quale l'API Address Validation può convalidare completamente l'indirizzo. Nella maggior parte dei casi, un livello di granularitàPREMISE
oSUB_PREMISE
indica un indirizzo di qualità che può essere pubblicato.geocodeGranularity
: descrive il livello di dettaglio del geocodificato associato all'indirizzo. Ad esempio, i record di Google potrebbero indicare l'esistenza di un numero di appartamento, ma non la posizione esatta di quel particolare appartamento all'interno di un grande complesso residenziale. In questo caso,validationGranularity
èSUB_PREMISE
, mageocodeGranularity
is
PREMISE.
Consulta la pagina Granularità nella guida di riferimento. |
Completezza dell'indirizzo
L'esito restituisce la proprietà addressComplete
come indicatore per un
indirizzo di alta qualità, il che significa nello specifico che non ha componenti mancanti,
irrisolti o imprevisti:
"verdict": {
"inputGranularity": "PREMISE",
"validationGranularity": "PREMISE",
"geocodeGranularity": "PREMISE",
"addressComplete": true
}
Quando l'indirizzo presenta componenti mancanti, non risolti o imprevisti, il campo viene impostato su false
.
Vedi addressComplete in Esito e Indirizzo nella guida di riferimento. |
Qualità degli indirizzi
Una serie di possibili campi indica problemi con i componenti dell'indirizzo o modifiche apportate, come i 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
}
Vedi il Esito nella guida di riferimento. |
Le proprietà address
e addressComponent
La proprietà address
fornisce la formattazione dell'indirizzo elaborato fornito nella richiesta, oltre a riepiloghi dell'indirizzo a livello di componente, tra cui parti dell'indirizzo con errori ortografici, parti errate sostituite e parti mancanti dedotte.
Vedi Address nella guida di riferimento. |
La proprietà addressComponent
è un sottocomponente di address
che fornisce
un elenco dettagliato degli elementi, o componenti, dell'indirizzo elaborato dall'API Address Validation. L'API identifica ciascun campo del componente in base a nome, tipo e livello di conferma.
Vedi addressComponent nella guida di riferimento. |
La proprietà geocode
La proprietà geocode
indica la località geocodificata associata all'indirizzo
di input. Questa proprietà fornisce dettagli sulla località stessa, come l'ID della località.
Vedi Geocode nella guida di riferimento. |
La proprietà metadata
Questa proprietà potrebbe non essere compilata per ogni indirizzo elaborato dall'API Address Validation, ma indica se l'indirizzo è di tipo residenziale, aziendale o di una casella postale.
Vedi Copertura dell'API Address Validation e il riferimento per Address metadata .
|
La proprietà uspsData
Questa proprietà fornisce informazioni utili per gli indirizzi postali degli Stati Uniti.
Tuttavia, non è garantito che il campo venga compilato completamente per ogni indirizzo convalidato dal servizio. Per questo motivo, non devi fare affidamento su questa proprietà come
unico strumento per convalidare gli indirizzi, ma controlla anche verdict
e
address
.
Vedi Gestire gli indirizzi negli Stati Uniti e il riferimento per UspsData .
|