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, orROUTE
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
oraddress.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.
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 totrue
, 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 existsUNCONFIRMED_BUT_PLAUSIBLE
indicates that the component could not be confirmed but it is plausibleUNCONFIRMED_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
isSUB_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
isPREMISE
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 outputformattedAddress
andpostalAddress
field.geocodeGranularity
isPREMISE_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.