Informazioni su una risposta di convalida degli indirizzi di base

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

{
  "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 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 quattro 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 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 geocodice. La specificità dell'indirizzo nella risposta validationGranularity è un indicatore chiave che indica se un indirizzo può essere consegnato o meno.

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 influenza il livello di dettaglio dell'indirizzo nella risposta di convalida. Ad esempio, un indirizzo con inputGranularity inferiore a PREMISE sotto livello non genera generalmente 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à PREMISE o SUB_PREMISE indica un indirizzo di qualità che probabilmente può essere consegnato.
  • 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 esatta per quel particolare appartamento all'interno di un grande complesso residenziale. In questo caso, validationGranularity è SUB_PREMISE ma geocodeGranularityisPREMISE".
Consulta la sezione 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, non risolti o imprevisti:

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

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

Consulta addressComplete sotto Esito e Indirizzo nella guida di riferimento.

Qualità degli indirizzi

Una serie di possibili campi indica problemi con i componenti degli indirizzi o modifiche a essi, come componenti di 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 il Esito nella guida di riferimento.

Proprietà address e addressComponent

La proprietà address fornisce la formattazione per l'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 componenti) dell'indirizzo elaborato dall'API Address Validation. L'API identifica ogni componente fornito dal campo tramite nome, tipo e livello di conferma.

Consulta addressComponent nella guida di riferimento.

La proprietà geocode

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

Consulta Geocode nella guida di riferimento.

La proprietà metadata

Questa proprietà potrebbe non essere compilata per tutti gli indirizzi elaborati dall'API Address Validation, ma indica se l'indirizzo è di tipo residenziale, aziendale o postale.

Vedi Copertura 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 completamento di ogni indirizzo convalidato dal servizio. Per questo motivo, non devi considerare questa proprietà come unico mezzo per convalidare gli indirizzi, ma controlla anche verdict e address.

Vedi Gestire gli indirizzi degli Stati Uniti e il riferimento per UspsData.
Indietro
Invia una richiesta di convalida dell'indirizzo
Avanti
Crea la tua logica di convalida