This document describes a process for building an address checking system to
handle a variety of responses from the Address Validation API.
It covers how to build your logic to correctly use the response, to investigate
other signals from the API, and when and how to prompt your customers for more
information.

In general the API response determines the following ways your system should
handle an address:

- **Fix**---the address is low quality. You should prompt for more information.
- **Confirm**---address is high quality, but has changes from the input address. You might prompt for confirmation.
- **Accept**---address is high quality. You can accept the address provided.

## Key purpose

This document helps you modify your system to best analyze the API response and
determine the next actions to take with supplied addresses. The following
pseudocode illustrates a possible flow.

    if (the API response indicates significant problems in the address)
        FIX - prompt the user to fix the address
    else if (the API response indicates less significant problems in the address)
        CONFIRM - confirm with the user that the address is correct
    else
        ACCEPT - continue with the address returned by the API.

The exact logic depends on your situation; see [Implementation guidance](https://developers.google.com/maps/documentation/javascript/address-validation/build-validation-logic.md.txt#implementation_guidance)
for more details. You can also use our open source implementation of this logic,
which is in the [Extended Component Library](https://github.com/googlemaps/extended-component-library/blob/main/src/address_validation).

## Workflow overview

The table below summarizes two actions for your system:

1. **The workflow to use** based on the fix, confirm, accept behavior.
2. **The *first* signals to check for** from the response. The signals described here come from the `verdict` property and are *not the only
   signals* to check for, but provide an initial indicator of the address quality. Each behavior type corresponds to a section in this document describing further signals you might also need to investigate.

Your system behavior **[Fix the address](https://developers.google.com/maps/documentation/javascript/address-validation/build-validation-logic.md.txt#fix-address)** The response from the `verdict` indicates important missing
information that should be provided. The address returned by the API may
not be of deliverable quality.

#### Workflow

1. Investigate address components if necessary.
2. Prompt customer to fix address issues.
3. Request validation for the updated address.
4. Proceed with address.

#### Verdict signals

**Any** of the following apply:

- [`validationGranularity`](https://developers.google.com/maps/documentation/javascript/reference/address-validation.md.txt#Granularity) set to `OTHER`.
- [`addressComplete`](https://developers.google.com/maps/documentation/javascript/reference/address-validation.md.txt#Verdict.addressComplete) is `false`.
**[Confirm the address](https://developers.google.com/maps/documentation/javascript/address-validation/build-validation-logic.md.txt#confirm-address)** The response from the `verdict` indicates a deliverable
address, but has made changes to the original input: inferring data that
is either spell corrected, or data that can be confirmed.

#### Workflow

1. Corrections needed:
   1. Investigate address components if necessary.
   2. Request validation for the updated address.
   3. Proceed with address.
2. No corrections needed:
3. Proceed with address.

#### Verdict signals

**All** of the following apply:

- [`validationGranularity`](https://developers.google.com/maps/documentation/javascript/reference/address-validation.md.txt#Granularity) contains `ROUTE`
- [`addressComplete`](https://developers.google.com/maps/documentation/javascript/reference/address-validation.md.txt#Verdict.addressComplete) is `true`.
- [`hasInferredComponents`](https://developers.google.com/maps/documentation/javascript/reference/address-validation.md.txt#Verdict.hasInferredComponents) field is `true` OR [`hasReplacedComponents`](https://developers.google.com/maps/documentation/javascript/reference/address-validation.md.txt#Verdict.hasReplacedComponents) field is `true`.
**[Accept the address](https://developers.google.com/maps/documentation/javascript/address-validation/build-validation-logic.md.txt#accept_an_address)** The Address Validation API response indicates an excellent quality address.

#### Workflow

Proceed with returned address.

#### Verdict signals

**All** of the following apply:

- [`validationGranularity`](https://developers.google.com/maps/documentation/javascript/reference/address-validation.md.txt#Granularity) contains `PREMISE` or better.
- [`addressComplete`](https://developers.google.com/maps/documentation/javascript/reference/address-validation.md.txt#Verdict.addressComplete) is `true`.
- **No** inferred or replaced components.

### Implementation guidance

When designing how your system responds to address validation signals,
the following recommendations can help you build a more effective response
model. However, these are only recommendations, so bear in mind that your
implementation should suit your business model.

|   | **Guidance** | **Details** |
| Risk level | Take into account the level of tolerance for your situation when balancing between prompting for corrections and accepting the address as entered. | The Address Validation API returns a variety of signals that you can incorporate with your risk level to optimize your validation process. For example, if an address has an unconfirmed street number, you can still accept it. On the other hand, if your business operation requires greater address precision, you might prompt your user. For an example that could fall into either category, see [Non-US unconfirmed street number](https://developers.google.com/maps/documentation/javascript/address-validation/accept-address-example.md.txt#non-us_unconfirmed_street_number) in **Accept address - examples**. |
| Accept addresses | It's a good practice to allow your system to accept the original entry if the customer does not respond to prompts. | In these cases, the customer might have entered an address not in the system, such as for new construction. |
|---|---|---|

> [!NOTE]
> **Try the demo.** The rest of this document uses a variety of examples to help you understand the fix, confirm, accept flow process described above. You can explore results from these examples by entering them in the [Address Validation in Maps JavaScript API demo](https://developers.google.com/maps/documentation/javascript/address-validation/demo.md.txt).

## Fix an address

Fix an address when the results clearly indicate that the address is not
deliverable. Your system can then prompt the customer to provide the necessary
information, after which you reissue your workflow to get a deliverable
address.

### Fix signals

The Address Validation API provides a number of signals to let you know if an
address should be fixed.

#### 1. Validation granularity and missing components

These two signals provide the best indication of a problematic address:

- Whenever the [`validationGranularity`](https://developers.google.com/maps/documentation/javascript/reference/address-validation.md.txt#Verdict.validationGranularity) field is `OTHER`, your system should investigate address component signals to learn more about where the error occurred and how to fix it.
- Whenever the post-processed [`address` object](https://developers.google.com/maps/documentation/javascript/reference/address-validation.md.txt#Address) returns a `missingComponentTypes` field, your system should check for that component. Missing components also render an address incomplete and non-deliverable.

#### 2. Other signals

The Address Validation API also provides the other signals to help
diagnose specific issues:

| **Suspicious components** | When the confirmation level enum for a component is `UNCOMFIRMED_AND_SUSPICIOUS`, it's likely that the component is incorrect. |
| **Unresolved component** | An [unresolvedToken](https://developers.google.com/maps/documentation/javascript/reference/address-validation.md.txt#Address.unresolvedTokens) is a part of the input not recognized as a valid part of an address. |
|---|---|

#### 3. US address signals

Certain fields applicable only to US addresses provide a useful signal that the
address is not deliverable and should be fixed. For an address that requires
fixing, you should see the following:

| `dpvConfirmation` | Either `N`, `D`, or empty. |
|---|---|

For details on `dpvConfirmation`, see
[Handle United States addresses](https://developers.google.com/maps/documentation/javascript/address-validation/handle-us-address.md.txt).

[Fix address examples](https://developers.google.com/maps/documentation/javascript/address-validation/fix-address-example.md.txt)

## Confirm an address

You confirm an address when the verdict indicates that the Address Validation API
either inferred or made changes to address components in order to produce a
validated address. In these cases, you have a deliverable address, but prefer
greater confidence that the resulting address is the one intended by the
customer.

To provide the customer with the correct prompting, your logic would identify
the components flagged by the service to determine which action or flag the API
applied to the component, such as `inferred`, `replaced`, or `spellCorrected`.
See [AddressComponent](https://developers.google.com/maps/documentation/javascript/reference/address-validation.md.txt#AddressComponent) in the reference.

> [!NOTE]
> **Note:** Consider your [risk level](https://developers.google.com/maps/documentation/javascript/address-validation/build-validation-logic.md.txt#implementation_guidance) when deciding whether to confirm the address with the customer or accept it as valid.

### Confirm signals

The Address Validation API provides a number of signals to let you know if an
address should be confirmed.

#### 1. Validation Granularity

A [`validationGranularity`](https://developers.google.com/maps/documentation/javascript/reference/address-validation.md.txt#Verdict.validationGranularity)
of `ROUTE` or better is acceptable, but either `PREMISE` or `SUBPREMISE`
provides a stronger signal of deliverability.

#### 2. Other signals

When deciding to confirm address entry with the customer, the verdict also
provides the following to determine what components to investigate:

| Inferred data | When the [`hasInferredComponents`](https://developers.google.com/maps/documentation/javascript/reference/address-validation.md.txt#Verdict.hasInferredComponents) field is `true`, you know that the API filled in information it gleaned from other address components. |
| Replaced data | When the [`hasReplacedComponents`](https://developers.google.com/maps/documentation/javascript/reference/address-validation.md.txt#Verdict.hasReplacedComponents) field is `true`, the API replaced entered data with data it deemed to make the address valid. |
|---|---|

#### 3. US address signals

Certain fields applicable only to US addresses indicate that your logic should
confirm details with the customer. Either of the following apply:

| `dpvConfirmation` | `S` For details on `dpvConfirmation`, see [Handle United States addresses](https://developers.google.com/maps/documentation/javascript/address-validation/handle-us-address.md.txt). |
| [Address response](https://developers.google.com/maps/documentation/javascript/reference/address-validation.md.txt#Address) | Contains `missingComponentTypes` field with the value of `subpremise`. > [!NOTE] > **Note** : if the field contains types other than `subpremise`, the action would fall into the fix address category. See the full list of [address types](https://developers.google.com/maps/documentation/geocoding/requests-geocoding#Types) in the Geocoding documentation. |
|---|---|

[Confirm address examples](https://developers.google.com/maps/documentation/javascript/address-validation/confirm-address-example.md.txt)

## Accept an address

You accept an address when the verdict provides a high degree of confidence that
the address is deliverable and can be used without further customer interaction
in the downstream process.

### Accept signals

The Address Validation API provides a number of signals to let you know if an
address should be confirmed.

#### 1. Validation Granularity

A `validationGranularity` of `PREMISE` or better is acceptable, but in some
cases, `ROUTE` still indicates a deliverable address.

#### 2. Other signals

A verdict for a high quality address should also provide the following:

- **No replaced data** . In this case, `hasReplacedComponents: FALSE`.
- **No inferred components** . In this case, `hasInferredComponents: FALSE`.

#### 3. US address signals

Certain fields applicable only to US addresses indicate a high quality address
that can be delivered to. For an acceptable US address, you should see the
following:

| `dpvConfirmation` | `Y` For details on [`dpvConfirmation`](https://developers.google.com/maps/documentation/javascript/reference/address-validation.md.txt#USPSData.dpvConfirmation), see [Handle United States addresses](https://developers.google.com/maps/documentation/javascript/address-validation/handle-us-address.md.txt). |
|---|---|

[Accept address examples](https://developers.google.com/maps/documentation/javascript/address-validation/accept-address-example.md.txt)