L'API Address Validation fornisce un corpo della risposta come oggetto JSON che contiene 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 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 è riportata 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 sezioni seguenti riepilogano tutti i campi della proprietà verdict
.
Consulta Verdict nella guida di riferimento. |
Granularità dell'indirizzo
La granularità dell'indirizzo si riferisce al livello di dettaglio utilizzato per determinare la specificità di un indirizzo o di un codice geografico. La specificità dell'indirizzo nella risposta validationGranularity
è un indicatore chiave per stabilire se un indirizzo è valido 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
solitamente non genera un valorevalidationGranularity
oPREMISE
.validationGranularity
: il livello di granularità fino al quale l'API Address Validation può convalidare completamente l'indirizzo. Nella maggior parte dei casi, un livello di granularità pari aPREMISE
oSUB_PREMISE
indica un indirizzo di qualità che è probabilmente recapitabile.geocodeGranularity
: descrive il livello di dettaglio del codice geografico associato all'indirizzo. Ad esempio, i record di Google potrebbero indicare l'esistenza di un numero di appartamento, ma non una posizione precisa di quel determinato appartamento all'interno di un grande complesso residenziale. In questo caso,validationGranularity
èSUB_PREMISE
, mageocodeGranularity
is
PREMISE.
Consulta la sezione Granularità della 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 sono presenti componenti mancanti, irrisolti o imprevisti:
"verdict": {
"inputGranularity": "PREMISE",
"validationGranularity": "PREMISE",
"geocodeGranularity": "PREMISE",
"addressComplete": true
}
Quando l'indirizzo presenta componenti mancanti, non risolti o inaspettati, il campo viene impostato su false
.
Consulta addressComplete in Verdict e Address nella guida di riferimento. |
Qualità dell'indirizzo
Un numero di possibili campi indica problemi con i componenti dell'indirizzo o aggiustamenti, 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
La proprietà address
fornisce la formattazione dell'indirizzo elaborato fornito nella richiesta, insieme a riepiloghi dell'indirizzo a livello di componente, tra cui parti con errori ortografici, parti sostituite errate e 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 elaborati dall'API Address Validation. L'API identifica ogni componente fornito dal campo in base al nome, al tipo e al livello di conferma.
Consulta addressComponent nella guida di riferimento. |
La proprietà geocode
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. |
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 una casella postale.
Consulta la 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 sia completamente compilato 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 la sezione Gestire gli indirizzi degli Stati Uniti e il riferimento per UspsData .
|