This document describes a number of real-world scenarios where the Address Validation API provides response signals that warrant a fix behavior from your system. See Workflow overview in Build your validation logic for context.
Common examples: fix
This section describes common examples where the Address Validation API provides response signals indicating lower quality address information.
Missing city and postal code
This example illustrates an entry having only the street address, with no city or postal code.
Address entered | Region |
---|---|
21 45 40th street | USA |
Verdict for missing city and postal code
The example below emphasizes the important signals from the response.
{
"inputGranularity": "PREMISE",
"validationGranularity": "OTHER",
"geocodeGranularity": "OTHER",
"hasUnconfirmedComponents": true
}
These signals indicate a non-deliverable address, so you can query the
addressComponents
to learn more:
{
"componentName": {
"text": "21",
"languageCode": "en"
},
"componentType": "street_number",
"confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE"
},
{
"componentName": {
"text": "45 40th street",
"languageCode": "en"
},
"componentType": "route",
"confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE"
},
{
"componentName": {
"text": "United States",
"languageCode": "en"
},
"componentType": "country",
"confirmationLevel": "CONFIRMED"
}
The Address Validation API returns only the country (United States) as CONFIRMED
.
It returns all other address components as UNCONFIRMED_BUT_PLAUSIBLE
, with
some important omissions to the data, such as locality and postal code.
Missing street number
This example shows a missing street number.
Address entered | Region |
---|---|
Buckingham Palace Road, SW1W 9TQ London | UK |
Verdict for missing street number
{
"inputGranularity": "PREMISE_PROXIMITY",
"validationGranularity": "ROUTE",
"geocodeGranularity": "ROUTE"
}
The validationGranularity
is ROUTE
, which indicates a match to the street,
but not enough information to get to the premise. Additionally, the
addressComplete
property is missing from the verdict, and therefore it is
false
. A further query of the address
object reveals a missing component type:
"missingComponentTypes": [
"street_number"
]
Edge-case examples: fix
In some situations, whether you fix, confirm, or accept an address depends on your particular business scenario. The examples below illustrate scenarios that might not strictly fall into a fix category.
Unconfirmed street number
In this scenario, the Address Validation API cannot confirm the supplied street number, yet it indicates that the address is complete.
Address entered | Region |
---|---|
84 Buckingham Palace Road, SW1W 9TQ, London | UK |
Verdict for unconfirmed street number
The example below emphasizes the important signals.
{
"inputGranularity": "PREMISE",
"validationGranularity": "PREMISE_PROXIMITY",
"geocodeGranularity": "PREMISE_PROXIMITY",
"addressComplete" : true,
"hasUnconfirmedComponents": true
}
It's worth investigating the combination of a validation granularity only to
premise-level approximation along with unconfirmed components. A query of the
addressComponents
property shows the following unconfirmed componentType
:
{
"componentName": {
"text": "84",
"languageCode": "en"
},
"componentType": "street_number",
"confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE"
}
Here, the confirmation_level
of the street_number
is set to
UNCONFIRMED_BUT_PLAUSIBLE
. Unconfirmed means that the service cannot match
the street number of 84 in its dataset, and plausible means that the
component data could still be valid.
Missing subpremise
This scenario describes an address that is only missing a subpremise, such as an
apartment or department number. Otherwise, the Address Validation API can fully
validate the address. As is the case when any address component is missing, the
the addressComplete
is false
and therefore not present on manual inspection
of the verdict.
To illustrate, suppose a customer enters a valid address for the San Francisco city assessor's office, but misses the room number from the input.
Address entered | Region |
---|---|
1 Doctor Carlton B Goodlett Place, San Francisco, CA 94102 | USA |
Verdict for missing subpremise
In this example, the verdict does not display the addressComplete
property, so
therefore it is false
. Because of this, you know that at least one address
element is unexpected, unresolved, or missing.
{
"inputGranularity": "PREMISE",
"validationGranularity": "PREMISE",
"geocodeGranularity": "PREMISE",
"hasInferredComponents": true
}
An address
query reveals the following:
"missingComponentTypes": [
"subpremise"
]
Upon further inquiry, the USPS data provides a dpvConfirmation
code of
D
, which also indicates a missing subpremise.