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. The examples here are illustrative, but
not exhaustive. See [Workflow overview](https://developers.google.com/maps/documentation/javascript/address-validation/build-validation-logic.md.txt#workflow-overview)
in **Build your validation logic** for context.

> [!TIP]
> **Tip:** Open the [Address Validation demo](https://developers.google.com/maps/documentation/javascript/address-validation/demo.md.txt) and try validating the example addresses for yourself.

## 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
[verdict](https://developers.google.com/maps/documentation/javascript/reference/address-validation.md.txt#Verdict).

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

The `PREMISE_PROXIMITY` [granularity](https://developers.google.com/maps/documentation/javascript/reference/address-validation.md.txt#Granularity)
level 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:

```json
{
  "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, such as Kirkland.

> [!TIP]
> **Tip:** Check the correct address in the [demo](https://developers.google.com/maps/documentation/javascript/address-validation/demo.md.txt), using **451 7th Avenue South, Kirkland, WA 98033** to see the response for the originally intended address.

> [!TIP]
> **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](https://developers.google.com/maps/documentation/javascript/address-validation/confirm-address-example.md.txt#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](https://developers.google.com/maps/documentation/javascript/address-validation/confirm-address-example.md.txt#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](https://developers.google.com/maps/documentation/javascript/address-validation/confirm-address-example.md.txt#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

```json
{
  "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.

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

> [!TIP]
> **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

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

In addition to a [verdict](https://developers.google.com/maps/documentation/javascript/reference/address-validation.md.txt#Verdict)
with unconfirmed components, the Address Validation API returns the following
formatted address:

```json
"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:

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

> [!TIP]
> **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](https://www.postofice.co.uk) and
[How to address UK and international mail](https://www.postoffice.co.uk/mail/how-to-address-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

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

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

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

> [!IMPORTANT]
> 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.

> [!TIP]
> **Action:** For this scenario, the recommended action is to ignore this signal and accept the address.