![Flow diagram showing the high level overview of the testing
steps.](https://developers.google.com/static/maps/architecture/choose-an-address-validation-solution/images/address_validation_testing_flow.svg)

## Objective

Address Validation provides value for a variety of use cases and there are key
considerations beyond the raw quality of testing results we suggest you explore.
For example: a holistic view of compatible products in a user flow such as
[Place Autocomplete](https://developers.google.com/maps/documentation/places/web-service/place-autocomplete.md.txt) and [Maps](https://developers.google.com/maps/documentation/javascript/overview.md.txt), regional availability, and [enterprise
trust \& reliability](https://mapsplatform.google.com/resources/trust-center).

Once you've got to the point of evaluating Address Validation API, here's some
guidelines we recommend you use as part of your testing.

The goals of this test will be to:

1. Confirm [Address Validation API](https://developers.google.com/maps/documentation/address-validation) is suitable for your use case.
2. Verify how the Address Validation API meets your solutions requirements, such as:
   - Identifying good quality addresses.
   - Alerting to address inputs that are poor quality.
   - Making corrections to address data, including inferences, replacements, and spell corrections.
   - Providing a formatted address for shipping.
   - Alerting to missing or incorrect subpremise data (USA only).
3. Ensure you will receive a measurable benefit from implementing the API.

After performing your test, you will be able to answer the above questions, and
determine if the API is a good fit for your business.

## Prepare your data

Your test should be performed against a sample of your existing address data.
Don't hand pick data for the test, but choose random samples that are
representative of the geographies you operate in. This means that, if you
operate in both the United States and the United Kingdom, but 70% of your
business is performed in the UK versus 30% in the US, the sample should reflect
that split.

Use addresses from the point of capture. For example, if you are planning to
implement address validation within your ecommerce checkout, use addresses as
entered by your customers on the form, before any existing processing has
happened that may be replaced by implementing Address Validation API.

Prepare a sample size of around 5,000 - 10,000 records for the test.

## Call the API

*Section prerequisite: Understand how to* [*send an address validation
request*](https://developers.google.com/maps/documentation/address-validation/requests-validate-address).

Once you have prepared the data, you will need to run each address record
against the API.

See the [Address Validation API](https://developers.google.com/maps/documentation/address-validation) documentation for guidance on how to call
the API. We also have an article describing best practices for using [Address
Validation API to process addresses at high volume](https://developers.google.com/maps/architecture/high-volume-address-validation).

The outcome of this step should be data output from the API for each address
record. You'll then be able to analyze the results to determine the suitability
of the API for your use case. Whether that's using a spreadsheet, a database, or
another tool is up to you.

## Review the results

*Section prerequisite: Understand how to* [*handle the validation response*](https://developers.google.com/maps/documentation/address-validation/build-validation-logic.md.txt),
*especially the concept of Fix, Confirm, and Accept*.

In this section we will discuss output scenarios you may analyze to assess
solution fit.

**Overview of key API fields discussed in this document**

| **Response Data** | **What Is it?** | **How To Evaluate** | **How Does It Help?** |
|---|---|---|---|
| verdict.inputGranularity | Describes the input granularity of the address. | **SUB_PREMISE** **PREMISE** **PREMISE_PROXIMITY** **BLOCK** **ROUTE** **OTHER** | Lets you determine if the input address has enough data to potentially be valid. |
| verdict.validationGranularity | Describes the overall output validation of the address. | **SUB_PREMISE** **PREMISE** **PREMISE_PROXIMITY** **BLOCK** **ROUTE** **OTHER** | Lets you determine the overall address quality on output from the API. |
| verdict.hasInferredComponents | Signals if the API has inferred a component. | **True/False** | The API is able to add missing components where it can infer the data. For example, a missing State code. |
| verdict.hasReplacedComponents | Signals if the API has replaced a component. | **True/False** | The API is able to replace incorrect components with the correct data in some scenarios. |
| verdict.addressComplete | Signals if the address is complete. | **True/False** | If the API determines the output address has all necessary components, this will be true. |
| address.missingComponentTypes | Signal to warn if the address is missing components. | **See** [**table two**](https://developers.google.com/maps/documentation/places/web-service/supported_types#table2)**for values**. | Highlight missing components from an incomplete address. |

### Review valid addresses

Sort the returned data from the API to determine the set of addresses your
system would accept as valid. Key signals to look for from the API are:

- `verdict.validationGranularity` contains `PREMISE` or better.
- `verdict.addressComplete` is `true`.
- No inferred or replaced components.

See [accept an address](https://developers.google.com/maps/documentation/address-validation/build-validation-logic.md.txt#accept_an_address) for more information.

The output of this exercise should be a subset of the address data that would be
accepted as valid by your system. At this point, you can determine:

- Is the acceptance percentage rate acceptable?
- If you use an existing address validation workflow, is the acceptance rate equivalent or better?

#### Example: Valid address

| **Address entered** | **Region** |
|---|---|
| 76 Buckingham Palace Road, London SW1W 9TQ | UK |

**Verdict**

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

### Review invalid addresses

This step is an opportunity to manually review some of the address data that has
been marked as invalid, and see if, without using Address Validation API, that
invalid address could cause downstream issues.

Sort the returned data from the API to determine the set of addresses your
system would mark as invalid. Key signals to look for from the API are:

- `verdict.validationGranularity` set to `OTHER` or `ROUTE` depending on your [risk level](https://developers.google.com/maps/documentation/address-validation/build-validation-logic.md.txt#implementation_guidance).
- `verdict.addressComplete` is `false`.

See [fix an address](https://developers.google.com/maps/documentation/address-validation/build-validation-logic.md.txt#fix-address) for more information.

The output of this exercise should be a subset of the address data that would be
marked as invalid by your system. At this point, you can determine if the
invalid percentage rate is acceptable.

It's important to note that marking addresses as invalid is a core piece of
functionality of the Address Validation API, and a high rate of addresses marked
as invalid does not necessarily reflect poorly on the API. The API is giving you
information that there is something wrong with the address, and this could bring
efficiencies to your workflow by catching errors earlier, before causing issues
downstream.

#### Example: Invalid address

| **Address entered** | **Region** |
|---|---|
| 21 45 40th street | USA |

**Verdict**

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

#### Review missing or unconfirmed components

At this stage, missing or unconfirmed components can also be reviewed. This is
part of the [Address](https://developers.google.com/maps/documentation/address-validation/reference/rest/v1/TopLevel/validateAddress.md.txt#address) object in the return. The two fields are
`missingComponentTypes` and `unconfirmedComponentTypes`.

Use these fields to help detect the reason an address is marked as invalid by
the API, and collect the correct information for the address that would enable
it to be valid, by feeding back to the point of data collection the specific
field(s) that are incorrect. This is a way the API is providing value by giving
you specific information about the quality of your data.

##### Example: Missing \& unconfirmed component

| **Address entered** | **Region** |
|---|---|
| Fake St, New York, NY 10011 | USA |

**Verdict**

```json
{
     "inputGranularity": "ROUTE",
     "validationGranularity": "OTHER",
     "geocodeGranularity": "OTHER",
     "hasUnconfirmedComponents": true
}
```

**Missing \& unconfirmed components**

```json
"missingComponentTypes": [
    "street_number"
],
"unconfirmedComponentTypes": [
    "route"
]
```

### Review addresses with corrections

The Address Validation API is able to make corrections to input data, taking a
potentially invalid address input and outputting valid address data. This is one
way the API adds value, and it's important to capture this as part of the test.

Key signals to look for are:

- `inferred`, `replaced`, or `spellCorrected` set to `true` on any of the `addressComponents`.
- `verdict.hasInferredComponents`, or `verdict.hasReplacedComponents` set to `true`.

See [confirm an address](https://developers.google.com/maps/documentation/address-validation/build-validation-logic.md.txt#confirm-address) for more information.

The output of this exercise should be a subset of the address data that has had
a correction applied by the API.

A portion of this data can be manually reviewed to determine if the API is making
corrections to your data that would reduce friction in your downstream workflow.

#### Example: Address with a correction

| **Address entered** | **Region** |
|---|---|
| 76 **Bruckingm** Palace Road, London SW1W 9TQ | UK |

**Route `addressComponent`**

```json
{
    "componentName": {
        "text": "Buckingham Palace Road",
        "languageCode": "en"
    },
    "componentType": "route",
    "confirmationLevel": "CONFIRMED",
    "spellCorrected": true
}
```

### \[USA only\] Review address with missing or incorrect subpremise data

The Address Validation API is able to determine if a subpremise is either
missing or incorrect, for US addresses.

Key signals to look for are:

- In the [Address](https://developers.google.com/maps/documentation/address-validation/reference/rest/v1/TopLevel/validateAddress.md.txt#address) object:
  - `unconfirmedComponentTypes` contains `subpremise`
  - `missingComponentTypes` contains `subpremise`
- In the [UspsData](https://developers.google.com/maps/documentation/address-validation/reference/rest/v1/TopLevel/validateAddress.md.txt#uspsdata) object:
  - `dpvConfirmation` is `D` (subpremise missing)
  - `dpvConfirmation` is `S` (subpremise unconfirmed)

See [handle United States addresses](https://developers.google.com/maps/documentation/address-validation/handle-us-address.md.txt) for more information.

This test will show whether there is an issue in your data with missing or
incorrect sub premises such as apartment numbers. This can cause downstream
issues, especially for delivery use cases. The Address Validation API can add
value to your workflow by identifying this earlier on, allowing you to implement
steps to collect corrected data.

#### Example: Missing subpremise

| **Address entered** | **Region** |
|---|---|
| 111 8th Avenue, Manhattan, NY 10011 | US |

**Missing component**

```json
"missingComponentTypes": [
    "subpremise"
]
```

**USPS data DPV confirmation**

```json
"dpvConfirmation": "D"
```

### \[USA only\] Review USPS standardizedAddress

The Address Validation API also returns the USPS standardized address for United
State addresses. This is especially important if you require USPS formatted
addresses to be printed on your shipping labels.

[UspsAddress](https://developers.google.com/maps/documentation/address-validation/reference/rest/v1/TopLevel/validateAddress.md.txt#uspsaddress) can be reviewed to view this data, and determine if it adds
value to your workflow.

#### Example: USPS standardized address

```json
"standardizedAddress": {
    "firstAddressLine": "111 8TH AVE FL 11",
    "cityStateZipAddressLine": "NEW YORK NY 10011-5201",
    "city": "NEW YORK",
    "state": "NY",
    "zipCode": "10011",
    "zipCodeExtension": "5201"
}
```

## Conclusion

Start testing - begin your Address Validation API testing today to ensure
accurate address data, enhance customer experience, and streamline your business
operations. After following the test scenarios outlined above, you'll have the
information you need to determine whether the Address Validation API will bring
value to your workflow.

Suggested further reading:

- [Address Validation API developer documentation](https://developers.google.com/maps/documentation/address-validation)
- [Use Address Validation API to process addresses at high volume](https://developers.google.com/maps/architecture/high-volume-address-validation.md.txt)
- [Address Validation for Ecommerce Checkout](https://developers.google.com/maps/architecture/ecommerce-checkout-address-validation.md.txt)

## Contributors

[Henrik Valve](https://www.linkedin.com/in/henrikvalve/) \| DevX Engineer