Building location validation capability using Google Maps Platform

Objective

You often have needs for validating the location of a place. There are a few different services in Google Maps Platform which can help you with this use case. This document helps you choose between the two primary location validation services - Address Validation API and the Geocoding API.

Address Validation API is an offering from Google Maps Platform that helps customers validate whether an address is accurate or not.

Geocoding with the Geocoding API is the process of converting addresses into geographic coordinates, which you can use to place markers on a map or a position on the map.

A high level overview of differences between Address Validation and Geocoding API can be found here.

When to choose Address Validation vs Geocoding API

Address-Validation-vs-Geocoding

Notes about the above flow chart:

User interaction use case refers to when a user is present to interact with the results.
Places Autocomplete is a javascript API, so suitable for integrating with User Interfaces.
You might be aware of data quality issues in your existing addresses. So though you may just want geocodes, it’s advisable to run those locations via Address Validation API to correct the datasets.

There are many situations when you might choose, based on the above decision tree, to use one product over the other. But other situations may involve using both of the products to meet your goals.

You might choose to use use Address Validation API over Geocoding API when:

There is a high chance of questionable data, or where getting an incorrect address will have a negative downstream impact. This is because Address Validation API provides more feedback on why an input did not receive a high precision result.
You need to correct user inputs (e.g. misspelling or missing fields), which increases the likelihood of an accurate result on output.
Your target region returns more metadata from Address Validation API compared to the Geocoding API, such as classification of building type as residential vs commercial.

You might choose to use use Geocoding over Address Validation API when:

Your primary objective is to retrieve location of an address and accuracy of individual addresses may not be critical.
- For example, to generate a heatmap from a large set of data.
You need a global solution and Address Validation API is not available in all target regions.

The following are some examples that demonstrate Address Validation API capabilities compared to the Geocoding API.

Invalid Address Example

1 Fake St, Mountain View, CA 94043, USA

The Address Validation API breaks this input down into its individual address components (street, city, state, etc.). It can also give granular feedback as to why the address is not valid down to a PREMISE level.

Fake St does not exist in Mountain View, CA, and the Address Validation API reflects that on the returned component level details:

{
  "componentName": {
    "text": "Fake St",
    "languageCode": "en"
   },
   "componentType": "route",
   "confirmationLevel":"UNCONFIRMED_BUT_PLAUSIBLE"
 }

The important property to inspect in this case is confirmationLevel. By returning UNCONFIRMED_BUT_PLAUSIBLE against Fake St, the API has determined that it would be possible for a street to have that as a name, but it is not able to be matched to the supporting address data.

Using the API result as feedback, it can be deduced that the street component of this input (Fake St) is at fault.

Using the same address with the Geocoding API, it is able to make a match on “California” as you see in the screenshot from the geocoding tool which you can try out here:

alt_text

However, the result is a geocode of the whole state, with minimal feedback as to which components on the input were potentially faulty.

Spelling Error Example

76 Buckingamm Palace Road, Londn, SW1W 9TQ, GB

The above address contains a couple of spelling errors, one in the street name, and the other in the locality.

Both the Address Validation and Geocoding API are able to correct these mistakes and achieve the result of 76 Buckingham Palace Road, London, SW1W 9TQ. However, the Address Validation API can give more information on the process.

Take a look at one of the address components that was misspelled on input:

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

The Address Validation API returns a flag to indicate that a correction has been made to the field. Business logic could be implemented against this flag to double check the correction with the data provider, such as a customer in an ecommerce checkout.

Missing Data and Spelling Error Example

Bollschestraße 86, 12587, DE

The above address has a spelling error in the street name, and is missing the city (locality) of Berlin.

The Address Validation API is able to fix both of these errors and returns a PREMISE level geocode, and an address which is verified to the PREMISE level:

Bölschestraße 86, 12587 Berlin, DE

The Geocoding API is not able to successfully overcome the input errors in this case, and returns a result of ZERO_RESULTS.

Additional Address Metadata Example

111 8th Avenue Ste 123, New York, NY 10011-5201, US

This address is correct except for the unit number (Ste 123), which does not exist within the building.

The Address Validation API is able to validate the address to the PREMISE (111 8th Ave), and give some metadata about the property, including that it is a commercial

premises:

"business": true

Additionally, the dpvConfirmation value returned as part of the uspsData in the response is S:

"dpvConfirmation": "S"

A dpvConfirmation value of S indicates that the address is validated to the PREMISE level, but the unit number provided in the input is not associated with that address.

The Geocoding API is not able to provide this information.

Understanding Geocoding API response

Overview

If you use the Geocoding API, the geocode result contains various clues in the response which can be used for understanding details of the address provided.

The way the Geocoding API works is by resolving address components in a hierarchy.

For **example, 123 Example Street, Chicago, 60007, USA resolves in the following order:

/ Example Street/ Chicago/ 60007/ USA will be evaluated in that order. The first match in this case is Chicago and, more specifically, the 60007 ZIP Code. Therefore, it returns the following Place_id for that ZIP Code:

ChIJwRKzf8ixD4gRHiXqucwr_HQ

The Geocode API contains the following info in the response:

        "partial_match": true,
           "place_id": "ChIJwRKzf8ixD4gRHiXqucwr_HQ",
           "types": [
               "postal_code"
           ]

The Geocoding API can confirm what kind of place this address belongs to. A list of address types returned by the Geocoding API can be found here.

If none of the components of the input are resolved, the API returns:

{
   "results": [],
   "status": "ZERO_RESULTS"
}

Making a request with just street address without a house number returns a result in the form:

"types": [
  "route"
]

Which means that the Geocoding API could not find or match a street number.

Note: To know if an address exists, check if any of the parameters (such as types, partial_match, results, status) are set in the Geocoding API response. This will gradually increase the confidence level that an address may exist, but will not make it 100% accurate. That's why we need Address Validation API.

You can use the techniques above to increase confidence in address accuracy from a Geocoding API response alone. However unlike an Address Validation API result, Geocoding API will not return exact feedback to determine result accuracy.

Location type

To understand this section properly, you need to understand the different location types that could be returned from a Geocoding API response:

ROOFTOP indicates that the returned result is a precise geocode for which we have location information accurate down to street address precision.
RANGE_INTERPOLATED indicates that the returned result reflects an approximation (usually on a road) interpolated between two precise points (such as intersections). Interpolated results are generally returned when rooftop geocodes are unavailable for a street address.
GEOMETRIC_CENTER indicates that the returned result is the geometric center of a result such as a polyline (for example, a street) or polygon (region).
APPROXIMATE indicates that the returned result is none of the above.

If a Geocoding API returns a location_type of ROOFTOP or RANGE_INTERPOLATED, it does not necessarily mean that the address exists. Similarly, if a Geocoding API returns with the partial_match flag set to true, it might still be the right result for you.

This type of false matching is a very difficult problem to solve with Geocoding API. At the very least, you might consider implementing some basic post processing validation on the country and locality of the request / response. Even better, look to compare the actual street addresses for misspellings and/or an incomplete address.

Note: If you decide to use the Geocoding API, it is recommended that you perform data quality checks between the initial request and the Geocoding API response regularly.

Partial match and false matching

If an address is a partial match, meaning the Geocoding API could not exactly identify the address, then the response contains:

"partial_match": true,
"types": [
           "locality",
           "political"
         ]

Even more important than the location types above is to consider when partial_match = true is in the response. partial_match indicates that the Geocoding API did not return an exact match for the original request, though it was able to match part of the requested address.

You might want to examine the original request for an incomplete address. Partial matches most often occur for street addresses that do not exist within the locality specified in the request. Partial matches may also be returned when a request matches two or more locations in the same locality.

For example, "21 Henr St, Bristol, UK" returns a partial match for both Henry Street and Henrietta Street. Note that if a request includes a misspelled address component, the Geocoding API might suggest an alternate address. Suggestions triggered in this way will not be marked as a partial match.

Synthetic Addresses

The Geocoding API may return locations for "synthetic" addresses that don't exist as precise locations in Google’s database.

In such scenarios the response object often contains a long Place ID, and the following property: geometry.location_type=APPROXIMATE.

If you encounter these indicators in the response, please consider marking the input address as an invalid and try to re-validate it by another means.

Note: This is another example where with Address Validation API, you get direct feedback if an address does not exist.

Understanding Address Validation API response

There is already great documentation on how to understand the responses from Address Validation API, so we will not get into further details here.

Overview of the response object can be found here.
Demo which illustrates the different components of the response is here
In the Address Validation for checkout document there is detailed description of how to differentiate between good vs bad addresses.

Best practices

Specifying geography

While making calls to either Address Validation or Geocoding APIs, it’s best practice to try to limit the geography in which to search for that address. The two APIs implement this in two different ways:

Geocoding API - Region Biasing

If you know the geocodes are going to be within a certain country, you get much better results by using Region Biasing. For example, if you are geocoding in Canada, we recommend adding &region=ca to your requests to bias towards Canada. Please note that Region Biasing only prefers results within that region. You can still get results outside of the region.
Address Validation API - Region Code

In a similar fashion, the Address Validation API produces more accurate results if an ISO2 code is passed in the request, using the regionCode field.

Storing place IDs

To store information from Google Maps Platform about the location for future requests, you can store the place ID indefinitely in your database as an attribute of the location. You should only need to make a Find Place request one time per placeID. You can also search for the place ID every time a user requests transaction details.

To ensure you always have the most updated information, refresh place IDs every 12 months using a Place Details request with the place_id parameter.

Note: Please make sure to also review the best practices guide for Geocoding.

Conclusion

This document describes the core differences between the Address Validation and Geocoding APIs. In summary, consider using Address Validation API when:

An accurate mailing address is required, especially for deliverability purposes.
The input data is known to be of poor quality. Address Validation API is more forgiving of input errors, will highlight unverifiable address components, and make corrections to the input data.
More information is required for an address, such as Residential vs Commercial (available in select regions).

Next Steps

Download the Improve checkout, delivery, and operations with reliable addresses Whitepaper and view the Improving checkout, delivery, and operations with Address Validation Webinar.

Contributors

Google maintains this article. The following contributors originally wrote it.

Principal authors:

Henrik Valve | Solutions Engineer

Thomas Anglaret | Solutions Engineer

Sarthak Ganguly | Solutions Engineer