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.

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.

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
}

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
}

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
}

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.