Comprendere la risposta di convalida

L'API Address Validation prende un indirizzo come input. L'API restituisce quindi una risposta contenente:

  • Il verdetto per la convalida dell'intero indirizzo e della convalida di ogni componente dell'indirizzo (numero, via, città e così via).

  • Una singola stringa contenente l'indirizzo completo determinato dall'API.

  • Singole proprietà che contengono ciascun componente dell'indirizzo come determinato dall'API.

  • Un elenco di eventuali componenti di indirizzi mancanti, di componenti di indirizzi non confermati e di componenti degli indirizzi che non è stato possibile risolvere.

  • La geocodifica dell'indirizzo.

  • Per le regioni "US" e "PR", i dati USPS per l'indirizzo.

Utilizzando la risposta dell'API, puoi assicurarti che l'indirizzo esista e sia della qualità necessaria per le tue esigenze. Se la risposta dall'API indica che un indirizzo è incompleto o non corretto, puoi chiedere all'utente di aggiornare l'indirizzo. Una volta che l'utente ha completato l'aggiornamento, utilizza l'API per convalidare l'indirizzo aggiornato.

Questo documento descrive come elaborare la risposta API e come gestire alcuni errori comuni nell'indirizzo di input rilevato dall'API.

Nota: per farti un'idea migliore di come l'API gestisce gli errori con l'indirizzo di input, prova la demo. La demo consente di inserire indirizzi e quindi di visualizzare la risposta come contenuto visualizzato e come oggetto JSON.

Informazioni sulla risposta

L'oggetto JSON che rappresenta la risposta di convalida contiene due proprietà di primo livello: result, di tipo ValidationResult e 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 descrive come interpretare la proprietà result. Per maggiori informazioni su responseID, consulta le pagine Convalidare un indirizzo aggiornato e Fornire un feedback di convalida dell'indirizzo.

Informazioni sulla proprietà dell'esito

La proprietà verdict nella risposta di convalida indica i risultati complessivi della convalida. La proprietà verdict contiene le seguenti proprietà:

  • inputGranularity

    Indica la granularità dell'indirizzo di input come determinato analizzando l'indirizzo, ma non convalidandolo. Ad esempio, queste proprietà possono contenere PREMISE per un indirizzo che si risolve nel risultato a livello di edificio, BLOCK per un indirizzo che si risolve in un blocco o ROUTE per un indirizzo granulare a un percorso, come una strada, una strada o un'autostrada.

  • validationGranularity

    Indica la granularità in cui l'API può convalidare l'indirizzo. Tieni presente che questa è la granularità dell'indirizzo convalidato e non la granularità dell'indirizzo restituito in address.formattedAddress o address.postalAddress.

  • geocodeGranularity

    Indica la granularità della posizione geocodificata generata.

  • addressComplete

    True se l'indirizzo è considerato completato dall'API. Ciò significa che non esistono token non risolti (stringhe di indirizzi o simboli), componenti di indirizzi imprevisti o componenti di indirizzi mancanti nella proprietà address.

  • hasUnconfirmedComponents, hasInferredComponents e hasReplacedComponents

    Proprietà che indicano se almeno un componente dell'indirizzo non può essere categorizzato o convalidato, se è stato dedotto almeno un componente dell'indirizzo (aggiunto) che non era nell'input e se è stato sostituito almeno un componente dell'indirizzo.

Verdetto per un indirizzo completo con componenti dedotti

L'esempio seguente mostra la proprietà verdict per un indirizzo completo con componenti dedotti:

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

Nota che la granularità si risolve in una premessa e che l'indirizzo è completo, ma l'API ha dedotto il valore di alcuni componenti. In questo esempio, l'indirizzo di input ha omesso il codice postale degli Stati Uniti che l'API è riuscita a dedurre dal resto dell'indirizzo. Per un esempio più completo, consulta Componenti degli indirizzi dedotti.

Verdetto per un indirizzo con componenti non confermati

Sebbene un indirizzo di input possa essere considerato completo anche se esistono componenti dedotti, un indirizzo non può essere considerato completo se sono presenti token dell'indirizzo irrisolti, componenti di indirizzi imprevisti o componenti di indirizzi mancanti.

Nel prossimo esempio, il valore hasUnconfirmedComponents è impostato su true per indicare che l'indirizzo ha almeno un componente dell'indirizzo che non può essere classificato o convalidato:

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

In questo caso, la granularità dell'indirizzo convalidato e geocodificato è impostata su OTHER e la proprietà addressComplete viene omessa dalla risposta, a indicare che l'indirizzo non è completo. Per un esempio più completo, consulta Componenti di indirizzi mancanti e non confermati.

Risposte di esempio

Le seguenti sezioni mostrano le risposte per diversi scenari, tra cui un indirizzo completo e gli errori di convalida dell'indirizzo più comuni. In questi esempi:

  • Se la risposta contiene addressComplete impostato su true, l'API ha stabilito che l'indirizzo di input era di buona qualità.

  • Se l'API Address Validation indica che l'indirizzo ha subito modifiche significative o che contiene errori, devi confermare al cliente l'indirizzo restituito.

Indirizzo completo di buona qualità

Quando l'API determina che un indirizzo è completo, imposta addressComplete su true nella proprietà verdict della risposta.

Ad esempio:

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

La proprietà address della risposta contiene tutti i dettagli dell'indirizzo come determinato dall'API. La risposta include la proprietà formattedAddress, che contiene l'indirizzo corretto e convalidato come stringa di una sola riga. Ti consigliamo di utilizzare l'indirizzo su una sola riga contenuto nel campo formattedAddress per l'indirizzo completo, poiché può contenere correzioni e aggiunte minori, come l'uso di lettere maiuscole e ZIP+4 negli Stati Uniti.

La proprietà address indica anche eventuali problemi, come determinato dall'API, per ciascun componente dell'indirizzo. Per ogni componente, ad esempio nome della via o città, il campo address contiene un campo confirmationLevel. I valori possibili sono:

  • CONFIRMED indica che l'API è riuscita a verificare che il componente esiste
  • UNCONFIRMED_BUT_PLAUSIBLE indica che non è stato possibile confermare il componente, ma è plausibile
  • UNCONFIRMED_AND_SUSPICIOUS indica che il componente non è stato confermato e che potrebbe essere sbagliato.

Ad esempio:

"address": {
  // Validated address as a single string.
  "formattedAddress": "1600 Amphitheatre Parkway, Mountain View, CA 94043-1351, USA",
  // Individual validated address components.
  "postalAddress": {
    "regionCode": "US",
    "languageCode": "en",
    "postalCode": "94043-1351",
    "administrativeArea": "CA",
    "locality": "Mountain View",
    "addressLines": [
      "1600 Amphitheatre Pkwy"
    ]
  },
  // Validation results for each component.
  "addressComponents": [
    {
      "componentName": {
        "text": "1600",
        "languageCode": "en"
      },
      "componentType": "street_number",
      "confirmationLevel": "CONFIRMED"
    },
    {
      "componentName": {
        "text": "Amphitheatre Pkwy",
        "languageCode": "en"
      },
      "componentType": "route",
      "confirmationLevel": "CONFIRMED"
    },
    …
  ]
  // List of any missing, unconfirmed, or unresolved address components.
  // These properties are omitted from the response if they are empty.
  "missingComponentTypes": [],
  "unconfirmedComponentTypes": [],
  "unresolvedTokens": []
}

Componenti degli indirizzi dedotti

Se l'indirizzo di input non contiene un indirizzo completo, l'API tenta di aggiungere eventuali componenti mancanti dell'indirizzo alla risposta. Questi componenti aggiunti sono definiti componenti di indirizzo dedotti.

Ad esempio, utilizzi il seguente indirizzo di input:

{
  "address": {
    "regionCode" : "US",
    "locality" : "Mountain View",
    "addressLines" : ["1600 Amphitheatre Pkwy"]
  }
}

Tieni presente che questo indirizzo di input non contiene un codice postale degli Stati Uniti. L'API può determinare il codice postale dal resto dell'indirizzo di input e aggiungerlo alla risposta.

In questo esempio, la proprietà verdict imposta hasInferredComponents su true per indicare che l'API ha dedotto il valore di uno o più componenti. Tuttavia, poiché si tratta di una correzione minore, l'API imposta addressComplete su true per indicare che l'indirizzo di input era ancora di buona qualità.

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

Per il componente dedotto, l'API imposta inferred su true nell'elemento corrispondente dell'array addressComponents della proprietà address:

{
  "componentName": {
    "text": "94043"
  },
  "componentType": "postal_code",
  "confirmationLevel": "CONFIRMED",
  "inferred": true
}

Errori di ortografia nell'indirizzo di input

Sono comuni errori di ortografia in un indirizzo di input, come un errore di digitazione nella città o nello stato. Ad esempio, anziché "Mountain View" inserisci "MontainView" come località di un indirizzo:

{
  "address": {
    "regionCode" : "US",
    "locality" : "MontainView",
    "addressLines" : ["1600 Amphitheatre Pkwy"]
  }
}

In questo esempio, la proprietà verdict indica che ha dedotto il valore di uno o più componenti, oltre a impostare addressComplete su true per indicare che l'indirizzo di input era di buona qualità perché era ancora in grado di risolvere l'indirizzo:

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

L'API tenta di risolvere l'indirizzo con l'ortografia corretta. L'elemento dell'indirizzo corrispondente nell'array addressComponents della proprietà address mostra la stringa corretta nella proprietà text e indica anche che si è verificato un errore ortografico impostando spellCorrected su true:

{
    "componentName": {
        "text": "Mountain View",
        "languageCode": "en"
    },
    "componentType": "locality",
    "confirmationLevel": "CONFIRMED",
    "spellCorrected": true
}

Componenti degli indirizzi mancanti e non confermati

Gli utenti potrebbero omettere una parte dell'indirizzo di input. Nell'esempio riportato di seguito, l'utente inserisce un numero civico, ma non il nome della via:

{
  "address": {
    "regionCode": "US",
    "locality": "Mountain View",
    "addressLines": ["1600"]
  }
}

In questo caso, nell'esito la proprietà addressComplete omette perché sono presenti troppe informazioni mancanti per consentire all'API di risolvere l'indirizzo. L'API imposta inoltre hasUnconfirmedComponents su true per indicare che l'indirizzo contiene componenti non confermati:

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

Nota anche che validationGranularity e geocodeGranularity sono impostati su OTHER perché l'API non è riuscita a risolvere l'indirizzo.

Nell'array addressComponents della proprietà address, l'API contrassegna il componente del numero civico come UNCONFIRMED_BUT_PLAUSIBLE:

{
  "componentName": {
    "text": "1600",
    "languageCode": "en"
  },
  "componentType": "street_number",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE"
}

Infine, l'API completa gli array missingComponentTypes e unconfirmedComponentTypes della proprietà address con i componenti mancanti nell'input e quelli che non è stato in grado di confermare:

"missingComponentTypes": [
  "route",
  "postal_code"
],
"unconfirmedComponentTypes": [
  "street_number"
]

Informazioni sui diversi valori di granularità

I valori di granularità nella risposta forniscono insight sul grado di precisione o sulla precisione con cui l'API può interpretare un indirizzo. Ad esempio, utilizzi il seguente indirizzo di input:

{
  "address": {
    "regionCode": "US",
    "locality": "Northampton",
    "addressLines": ["6 South Main Street APT 456"]
  }
}

In questo esempio l'API trova il numero civico nel database USPS, ma non riesce a trovare il numero dell'appartamento. Inoltre, l'API non riesce a trovare un codice geografico preciso per il numero civico "6", ma ne può trovare uno per "4" e "8". In questo caso, l'API restituisce il seguente verdict:

"verdict": {
    "inputGranularity": "SUB_PREMISE",
    "validationGranularity": "PREMISE",
    "geocodeGranularity": "PREMISE_PROXIMITY",
    "addressComplete": true,
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}

In questa risposta:

  • inputGranularity è SUB_PREMISE perché l'API può analizzare l'indirizzo di input a livello di appartamento. inputGranularity si applica solo alla capacità delle API di analizzare l'indirizzo di input. Non si applica alla convalida eseguita sull'indirizzo.

  • validationGranularity è PREMISE perché l'API può convalidare l'esistenza del numero della via "6" ma non di "APT 456". Anche se l'API non può convalidare "APT 456", è ancora inclusa nel campo di output formattedAddress e postalAddress.

  • geocodeGranularity è PREMISE_PROXIMITY perché l'API è in grado di interpolare la posizione geografica, ma non ha trovato un codice geografico per l'indirizzo esatto.

Indirizzo creato in modo artificiale rilevato da USPS

Quando l'USPS identifica un indirizzo creato in modo artificiale, il campo errorMessage della proprietà uspsData della risposta contiene un messaggio di errore che descrive il problema. Ad esempio:

"uspsData": {
    "errorMessage": "AMS API processing was terminated due to the detection of
    what is determined to be an artificially created address. No address beyond
    this point has been validated and/or processed. If you believe this address
    was identified in error, please contact your Vendor."
}

L'invio di indirizzi creati artificialmente all'API può comportare la perdita dell'accesso al database USPS. Quando ricevi questo messaggio di errore, ti consigliamo di verificare l'origine dell'indirizzo per evitare che indirizzi più artificiali vengano inviati all'API.

Questa misura di sicurezza è progettata per impedire la creazione artificiale di un elenco di indirizzi rilevando quando un indirizzo inviato sembra essere stato costruito in modo artificiale e non è stato ottenuto in modo legittimo. Questo dovrebbe essere un evento raro.