Confirm address - examples

This document describes a number of real-world scenarios where the Address Validation API provides response signals for addresses that warrant a confirm behavior from your system. See Workflow overview in Build your validation logic for context.

Note: the examples here are illustrative, but not exhaustive.

Common examples: confirm

The following example illustrates the case of metropolitan areas with similar street names. Suppose a user intends to enter the address for Google Building D in Kirkland, WA, United States. However, instead of Kirkland as the city, they inadvertently enter Seattle.

Address entered	Region
Building D, 451 7th Avenue South, Seattle, WA 98033	US

Verdict for replaced data

The example below emphasizes the important signals from the response.

{
  "inputGranularity": "SUB_PREMISE",
  "validationGranularity": "PREMISE_PROXIMITY",
  "geocodeGranularity": "PREMISE_PROXIMITY",
  "addressComplete": true,
  "hasUnconfirmedComponents": true
  "hasReplacedComponents": true
}

The PREMISE_PROXIMITY indicates proximation of a building-level address, but is not as detailed as SUB_PREMISE, which is the granularity provided on input. The response also contains both unconfirmed and replaced components, so the combination tips this into the confirm category.

A query of the address components reveals the following areas of concern:

{
  "componentName": {
    "text": "451",
  },
  "componentType": "street_number",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
}
...
{
  "componentName": {
    "text": "98104",
  },
  "componentType": "postal_code",
  "confirmationLevel": "CONFIRMED",
  "replaced": true
}
...
{
  "componentName": {
    "text": "Building D",
    "language_code": "en"
  },
  "componentType": "subpremise",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
}
.......

    "unconfirmedComponentTypes": [
      "street_number",
      "subpremise"
    ]

In this case, the Address Validation API found a close approximation to the provided address in Seattle, and it replaced the zip code, a higher-level component, to resolve to a Seattle address. This could be a valid replacement, but along with the fact that components were unconfirmed, it makes sense to ensure that the user intends to enter a Seattle address and not something else, like Kirkland.

Tip: Check the correct address in the demo, using 451 7th Avenue South, Kirkland, WA 98033 to see the response for the originally intended address.

Action: Confirm address entry with the customer.

Edge-case examples: confirm

The following examples illustrate the following edge case types:

• Minor inferences that ARE confirmed. The Address Validation API infers either the country, postal code, or state, but everything else is both provided and confirmed. The combination of both the granularity and confirmation level makes for a minor inference not necessarily needing a confirm action.
• Unexpected address component NOT confirmed. Unconfirmed address components add to the risk level of the address. This might warrant a confirm.
• Unexpected address component that IS confirmed. The component is not strictly required for a proper address, and the Address Validation API removes it from the output. Formatting issues don't generally warrant a confirm.

Minor inferences that ARE confirmed

When combined with confirmed data of a more granular level, the API can still make a correct inference if the input is missing only one component of the following types:

• City
• State
• Postal code
• Country

For example, a customer provides a valid street address for a McDonald's restaurant in Springfield, Massachusetts, but forgets to enter the city and provides a zip code without the 4-digit extension.

Address entered	Region
1402 Allen St, MA 01118	US

Verdict for missing city

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

In situations where the Address Validation API infers higher-level components in order to produce a deliverable address, you can have a higher level of confidence that the data from the system is correct. This is because inferred components that represent a wide geographic region are more readily matched to confirmed address components that are more granular. Even in countries where city names are repeated, such as Springfield in the United States, the other components combined with it can provide a unique address.

Using our example above, a scan across all address components shows that every component is confirmed, which means it matches the data stored by the Address Validation API, and that the service also infers two higher-level components.

{
  "componentName": {
    "text": "Springfield",
    "languageCode": "en"
  },
  "componentType": "locality",
  "confirmationLevel": "CONFIRMED",
  "inferred": true
},
{
  "componentName": {
    "text": "1806"
  },
  "componentType": "postal_code_suffix",
  "confirmationLevel": "CONFIRMED",
  "inferred": true
}

Action: Accept. Addresses such as these provide enough confirmed granularity, along with confirmation of inferred components, that your logic could accept these as valid without the need to prompt the customer.

Unexpected address component NOT confirmed

This scenario illustrates the importance of checking when components are not confirmed. If an address component is unexpected, the Address Validation API removes it from the output. In these cases, you can either accept the address or reconfirm it with the customer, depending on your risk level and confidence level.

For example, an address might be from a region where customers often enter harmless information ignored by the postal authority, in which case you'd accept the address. However, in some cases an unconfirmed component might not be what the customer wants.

Address entered	Region
1 Rue Grenache, la caritat 2, 34630 Saint-Thibéry	France

Verdict for unexpected address component not confirmed

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "unconfirmedComponents": true
}

In addition to a verdict with unconfirmed components, the Address Validation API returns the following formatted address:

"formattedAddress": "1 Rue Grenache, 34630 Saint-Thibéry, France",

A scan for unconfirmed components shows that the API removed la caritat 2 from the returned address:

{
  "componentName": {
    "text": "la caritat 2",
    "languageCode": "fr"
  },
  "componentType": "sublocality_level_1",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
  "unexpected": true
}

Action: Confirm. In this case, the sublocality, which can indicate a housing district or a neighborhood, might be correct but still ignored by the postal authority. However, given that this information is **not** confirmed by the Address Validation API, it makes sense to confirm this with the customer. At this point, you either ignore the removal or confirm it.

Unexpected address component that IS confirmed

This example illustrates inclusion of a UK county in the supplied address, which is a common practice. However, this is not a requirement by the UK postal authority and is essentially ignored. See postoffice.co.uk and How to address UK and international mail.

As a result, when a customer provides a county in a UK address, the service evaluates this as unexpected input.

Address entered	Region
33 Dunalley St, Cheltenham, Gloucestershire, GL50 4AP	UK

Verdict for unexpected address component that IS confirmed

{
   "inputGranularity": "PREMISE",
   "validationGranularity": "PREMISE",
   "geocodeGranularity": "PREMISE"
}

Here, address_complete evaluates to false and an analysis of the address component reveals an unexpected flag.

{
  "componentName": {
    "text": "Gloucestershire",
    "languageCode": "en"
  },
  "componentType": "administrative_area_level_2",
  "confirmationLevel": "CONFIRMED",
  "unexpected": true
}

This component is both unexpected and confirmed, which means the following:

• Confirmed as correct data. This indicates the component is the correct county that contains the address.
• Unexpected as input. Indicates a component not required for proper formatting of the address.

While Gloucestershire is the correct county for the entered address, the address itself is improperly formatted. Recall that the Address Validation API also evaluates information for proper formatting.

Action: For this scenario, the recommended action is to ignore this signal and accept the address.