Understand the validation response

The Address Validation API takes an address as input. The API then returns a response that contains:

• The verdict for the validation of the entire address and for the validation of each address component (street number, street name, city, etc.).

• A single string containing the complete address as determined by the API.

• Individual properties containing each component of the address as determined by the API.

• A list of any missing address components, of any unconfirmed address components, and of any address components that could not be resolved.

• The geocode of the address.

• For the "US" and "PR" regions, the USPS data for the address.

Using the API response, you can ensure that the address exists and is of the quality necessary for your needs. If the response from the API indicates that an address is incomplete or incorrect, you can prompt the user to update the address. After the user completes the update, use the API to validate the updated address.

This document describes how to process the API response and how to handle some common errors in the input address detected by the API.

Note: To get a better idea of how the API handles errors with the input address, Try the demo. The demo lets you enter addresses and then view the response as visualized content and as a JSON object.

About the response

The JSON object representing the validation response contains two top-level properties: result, of type ValidationResult, and 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"
}

This document describes how to interpret the result property. For more information on responseID, see Validate an updated address and Provide address validation feedback.

Understanding the verdict property

The verdict property in the validation response indicates the overall results of the validation. The verdict property contains the following properties:

• inputGranularity

  Indicates the granularity of the input address as determined by parsing the address but not validating it. For example, these properties can contain PREMISE for an address that resolves to the building level result, BLOCK for an address that resolves to a block, or ROUTE for address granular to a route, such as a street, road, or highway.

• validationGranularity

  Indicates the granularity that the API can validate the address to. Note that this is the granularity of the validated address and not the granularity of the address returned in address.formattedAddress or address.postalAddress.

• geocodeGranularity

  Indicates the granularity of the generated geocode location.

• addressComplete

  True if the address is considered complete by the API. That means there are no unresolved tokens (address strings or symbols), unexpected address components, or missing address components listed in the address property.

• hasUnconfirmedComponents, hasInferredComponents, hasReplacedComponents

  Properties that indicate if at least one address component cannot be categorized or validated, if at least one address component was inferred (added) that was not in the input, and if at least one address component was replaced.

Verdict for a complete address with inferred components

The following example shows the verdict property for a complete address with inferred components:

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

Notice that the granularity resolves to a premise and that the address is complete, but the API inferred the value of some components. In this example, the input address omitted the US ZIP code which the API was able to infer from the rest of the address. See Inferred address components for a more complete example.

Verdict for an address with unconfirmed components

While an input address can be considered complete even if there are inferred components, an address cannot be considered complete if there are any unresolved address tokens, unexpected address components, or missing address components.

In the next example, hasUnconfirmedComponents is set to true to indicate that the address has at least one address component that cannot be categorized or validated:

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

In this case, the granularity of the validated and geocoded address is set to OTHER and the addressComplete property is omitted from the response to indicate that the address is not complete. See Missing and unconfirmed address components for a more complete example.

Note: The default value of the addressComplete field is false. When a response message is parsed, and a field in the response message contains its default value, the field can be omitted from the response. Therefore, the addressComplete field is omitted from this response because it is false. For more information, see Default Values in the Language Guide (proto3) topic.

Example responses

The following sections show responses for different scenarios, including for a complete address and for common address validation errors. In these examples:

• If the response contains addressComplete set to true, then the API has determined that the input address was of good quality.

• If the Address Validation API indicates that it has made significant changes to the address or that there are errors in the address, then you need to confirm the returned address with your customer.

Complete address of good quality

When the API determines that an address is complete, it sets addressComplete to true in the verdict property of the response.

For example:

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

The address property of the response contains all the details of the address as determined by the API. The response includes the formattedAddress property, which contains the corrected and validated address as a single-line string. We recommend that you use the single-line address contained in the formattedAddress field for the complete address, as it can contain minor corrections and additions, such as capitalization and ZIP+4 in the USA.

The address property also indicates if there are any issues, as determined by the API, for each address component. For each component, such as street name or city, the address field contains a confirmationLevel field. Possible values include:

• CONFIRMED indicates that the API was able to verify that the component exists
• UNCONFIRMED_BUT_PLAUSIBLE indicates that the component could not be confirmed but it is plausible
• UNCONFIRMED_AND_SUSPICIOUS indicates that the component was not confirmed and is likely to be wrong.

For example:

"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": []
}

Inferred address components

If the input address does not contain a complete address, the API attempts to add any missing address components to the response. These added components are referred to as inferred address components.

For example, you use the following input address:

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

Notice that this input address does not contain a US ZIP code. The API can determine the ZIP code from the rest of the input address and add it to the response.

In this example, the verdict property sets hasInferredComponents totrue to indicate that the API inferred the value of one or more components. However, because this was a minor correction, the API sets addressComplete to true to indicate that the input address was still of good quality.

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

For the component that was inferred, the API sets inferred to true in the corresponding element of the addressComponents array of the address property:

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

Spelling errors in the input address

Spelling errors in an input address, such as a typo in the city or state, are common. For example, instead of "Mountain View" you enter "MontainView" as the locality portion of an address:

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

In this example, the verdict property indicates that it inferred the value of one or more components and also sets addressComplete to true to indicate that the input address was of good quality because it was still able to resolve the address:

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

The API attempts to resolve the address to the correct spelling. The corresponding address element in the addressComponents array of the address property shows the corrected string in the text property, and also indicates that there was a spelling error by setting spellCorrected to true:

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

Missing and unconfirmed address components

Users might omit a portion of an input address. In the example below, the user enters a street number but not a street name:

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

In this case, the verdict omits the addressComplete property because there is too much missing information for the API to be able to resolve the address. The API also sets hasUnconfirmedComponents to true to indicate that the address has unconfirmed components:

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

Notice also that the validationGranularity and geocodeGranularity are set to OTHER because the API could not resolve the address.

In the addressComponents array of the address property, the API marks the street number component as UNCONFIRMED_BUT_PLAUSIBLE:

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

And finally, the API populates the missingComponentTypes and unconfirmedComponentTypes arrays of the address property with the components missing from the input and those that it could not confirm:

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

Understand different granularity values

The granularity values in the response provide insight into how coarse or how fine the API can interpret an address. For example, you use the following input address:

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

In this example, the API finds the street number in the USPS database but cannot find the apartment number. In addition, the API cannot find a precise geocode for the street number, "6", but can find one for "4" and "8". In this case, the API returns the following verdict:

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

In this response:

• inputGranularity is SUB_PREMISE because the API can parse the input address to the apartment level. inputGranularity only applies to the APIs ability to parse the input address. It does not apply to the validation performed on the address.

• validationGranularity is PREMISE because the API can validate the existence of the street number "6" but not "APT 456". Even though the API cannot validate "APT 456", it is still included in the output formattedAddress and postalAddress field.

• geocodeGranularity is PREMISE_PROXIMITY because the API can only interpolate the geocode location, it could not find a geocode for the exact input street address.

Artificially created address detected by USPS

When the USPS identifies an artificially created address, the errorMessage field of the uspsData property of the response contains an error message describing the issue. For example:

"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."
}

Sending artificially created addresses to the API can lead to losing access to the USPS database. Upon receiving this error message, we recommend that you investigate the source of the address in order to prevent more artificial addresses from being sent to the API.

This security measure is designed to prevent the artificial creation of an address list by detecting when a submitted address appears to have been constructed artificially and not obtained legitimately. This should be a very rare occurrence.

Note: The properties other than uspsData in the API response are unaffected when an artificial address is detected.