Objective
Capturing accurate addresses from customer orders is critical for ecommerce because it helps to ensure that products can be successfully delivered, increase on-time deliveries, and reduce courier address correction charges.
This document describes best practices for using the Address Validation API in ecommerce checkout, including when to silently accept a good address, confirm the Address Validation response with the customer, or send the customer back to the address entry form to make manual corrections.
Google Maps Platform already offers a tutorial on how to improve checkout using Place Autocomplete service. This document extends that tutorial by adding the new capabilities of the Address Validation API, which is designed to identify address entry errors, thus helping to improve deliverability and make checkout more powerful.
What is address validation?
Address Validation (also known as address verification) is a process designed to identify whether inputted street and postal addresses exist, and is of a deliverable quality.
Why do you need address validation at checkout?
Unnoticed errors in addresses at checkout can cause serious delivery issues. Address validation at the checkout screen helps give you confidence that the address the customer entered for delivery is valid. This in turn, reduces failed and mis-deliveries, which is costly to the businesses.
The Places Autocomplete service and the Address Validation API allow the user to input their data correctly at check out quickly and easily. Some common scenarios which makes the Address Validation API an essential part of the checkout process are:
Typos
It can be quite common for customers to mistype when inputting their address, especially on a mobile device. For example, inputting New York as the locality for a Brooklyn address.
Phone orders
A person taking a phone order can easily misunderstand addresses or capture partial address information. This in turn leads to order delivery taking extra time or failing completely.
Buying gifts
People often buy products as gifts for friends and family whose address they may not know with 100% certainty. In such scenarios, the Address Validation API helps provide an added layer of confidence that the entered address is valid.
Customer needs additional address metadata
A package shipper or courier company often needs additional information to complete a delivery, such as Residential vs Commercial building type, or a USPS DPV value (USA only).
Differences due to different delivery companies
Local postal services are often more knowledgeable about a specific neighborhood than a small courier. So even if an apartment number or a local landmark is missing, some carriers (like your post office) might be able to deliver a package, where other carriers might fail.
If couriers do not have local knowledge of the delivery area, then the more information they have helps ensure a successful delivery. The corrections which the Address Validation API suggests can offer couriers a higher confidence that the package is deliverable.
Implementing Address Validation API
After a customer has entered their address, whether it was from Place Autocomplete or a manual entry, the entered address data can be sent to the Address Validation API.
The suggested time to call the Address Validation API is on click of the Next/Continue button on the address form, most likely leading to the payment processing page.
An end-to-end flow using the Address Validation API during checkout process can look like this:
Now we break down each step in detail.
Step 1: Address entry flow - using the Place Autocomplete service
The Place Autocomplete service should be implemented on the first line of the address entry form, giving suggestions to the customer as they enter their address details.
Autocomplete can simplify address entry in your application, leading to higher conversion rates and a seamless experience for your customers. It provides a single, quick entry field with "type-ahead" address prediction that can be used to automatically populate a billing or shipping address form.
By incorporating Autocomplete in your online shopping cart, you can:
- Significantly reduce keystrokes and total time required to place an order.
- Reduce address entry errors.
- Reduce cart abandonment.
- Simplify the address entry experience on mobile or wearable devices.
Some examples of how the flow screen can look like at this phase are shown here.
Step 2: Use the Address Validation API to validate addresses
We recommend you call the Address Validation API at checkout to confirm that the address is valid and complete.
However if for some reason the Address Validation API is not invoked in the default flow, we recommend invoking it at least under these scenarios:
- The customer used browser autofill instead of Autocomplete.
- The customer ignored Autocomplete input.
- Autocomplete was used, but the returned address was edited.
- You're processing a high value transaction where having a successful delivery is especially important.
- You are required to store consumer addresses for legal reasons.
Step 3: Provide visual confirmation
After address entry, provide the user visual confirmation of the delivery
location with a simple static map. This map offers the customer additional
assurance that the address is correct, and it reduces delivery/pickup failures.
The map can be shown on the page where customers enter the address, or even sent
within the confirmation email when they have completed the transaction. Both of
these use cases can be accomplished with the following APIs:
Maps JavaScript API provides an interactive map for displaying the user location. | Maps Static API allows for image embed within the webpage or at a later stage in an email. |
---|---|
![]() |
![]() |
Deep Dive - address acceptance scenarios
There are three main scenarios that can be defined from the response of the Address Validation API. The components in the response to check the address quality are highlighted, and the flowchart earlier in the document has an overall suggested flow for these described scenarios.
Scenario 1: Valid address
If the API returns a signal that the entered address was of good quality, the
checkout can move onto the next stage without any notification to the customer.
Signals that indicate a good quality address are:
- The
addressComplete
marker beingtrue
, - The validationGranularity at
PREMISE
orSUB_PREMISE,
and - None of the
address components
marked as:
inferred
spellCorrected
replaced
unexpected
We recommend taking the recommended address data from the Address Validation API, as this could contain minor corrections and additions, such as:
- Capitalization
- Formatting corrections, for example
- Street to St
- Correct ordering of address components
- ZIP+4 in the USA.
An example of how this feedback can be used in the validation process is shown below:
REQUEST | RESPONSE |
---|---|
"address": { "regionCode": "US", "locality": "Mountain View", "addressLines": ["1600 Amphitheatre Pkwy"] } |
"verdict": { "inputGranularity": "PREMISE", "validationGranularity": "PREMISE", "geocodeGranularity": "PREMISE", "addressComplete": true, "hasInferredComponents": true } … "addressComponents": [ { "componentName": { "text": "1600", "languageCode": "en" }, "componentType": "street_number", "confirmationLevel": "CONFIRMED" }, { "componentName": { "text": "Amphitheatre Parkway", "languageCode": "en" }, "componentType": "route", "confirmationLevel": "CONFIRMED" }, { "componentName": { "text": "Mountain View", "languageCode": "en" }, "componentType": "locality", "confirmationLevel": "CONFIRMED" } |
Scenario 2: Questionable address
The Address Validation API may indicate that there are meaningful changes to
the address, usually by the inclusion of inferred , spellCorrected , or
replaced on the individual fields,
the returned address should be confirmed with the customer. This can be done by
using a pop-up modal, with an option to select the entered address, or the
recommendation provided by the API.
"1600 amphiteatre parkway" matches to "1600 Amphitheatre Parkway, Mountain View, CA 94043-1351, USA"
|
![]() |
REQUEST | RESPONSE |
---|---|
"address": { "regionCode": "US", "addressLines": ["1600 amphiteatre parkway"] } |
"verdict": { "inputGranularity": "PREMISE", "validationGranularity": "PREMISE", "geocodeGranularity": "PREMISE", "addressComplete": true, "hasInferredComponents": true } … "address": { "formattedAddress": "1600 Amphitheatre Parkway, Mountain View, CA 94043-1351, USA", … "addressComponents": [ { "componentName": { "text": "1600", "languageCode": "en" }, "componentType": "street_number", "confirmationLevel": "CONFIRMED" }, { "componentName": { "text": "Amphitheatre Parkway", "languageCode": "en" }, "componentType": "route", "confirmationLevel": "CONFIRMED", "spellCorrected": true } ... { "componentName": { "text": "Mountain View", "languageCode": "en" }, "componentType": "locality", "confirmationLevel": "CONFIRMED", "inferred": true } |
Note: Route missing “h”, missing locality name (Mountain View) |
Scenario 3: Invalid address
If the response from the Address Validation API indicates an invalid address, the customer should be redirected to the address entry form to check their entered data. When the Address Validation API cannot find a match candidate for an address, it qualifies the individual components of the address, and marks missing/invalid data, so it is possible to flag fields that need additions or corrections. |
![]() |
REQUEST | RESPONSE |
---|---|
"address": { "regionCode": "US", "addressLines": ["123 fake street new york"] } |
"verdict": { "inputGranularity": "PREMISE", "validationGranularity": "ROUTE", "geocodeGranularity": "ROUTE", "hasUnconfirmedComponents": true, "hasInferredComponents": true } … "addressComponents": [... {"componentName": { "text": "123", "languageCode": "en" }, "componentType": "street_number", "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE" }, { "componentName": { "text": "fake street", "languageCode": "en" }, "componentType": "route", "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE" }, {"componentName": { "text": "New York", "languageCode": "en" }, "componentType": "locality", "confirmationLevel": "CONFIRMED" } … |
The logic described above can be implemented as part of the checkout flow as shown in the following flow diagram:
Tips to further enhance checkout
It is important that customers are not blocked from checking out due to entering an invalid address. Logic should not be constructed in a way that sends customers in an infinite loop if the API consistently indicates their entry is an invalid address.
We recommend that customers are given up to two chances to enter their address, and on the second attempt, their entry should be accepted even if it does not validate. This can be achieved by either allowing the customer to ‘force-proceed' when shown a pop up modal with the API suggestion, or silently accepting the second attempt at address entry, even if the address does not fully validate. Address inputs that do not fully validate can be flagged for manual review downstream by a customer service department before a product is shipped.
An example of why this is important is new construction. There may be a gap between when new building construction is finished and when that building's address is populated in postal address databases. Customers should be able to force-proceed through the checkout page with their typed address, which may not seem validated just yet.
You can optionally use the provideValidationFeedback
method of the Address
Validation API to provide feedback to Google about a specific validation
attempt. Learn more
here.
Addresses can be displayed on the UI or cached in a database if in alignment with the Address Validation API Service Specific Terms. If the addresses are cached in a database, then we need to ensure the following:
- Addresses can be cached only against a user.
- Formatted address and most other attributes can only be cached after obtaining user consent.
You will find that some Autocomplete and/or Address Validation API responses are partial or incomplete. Based on your geography and specific business needs, we recommend implementing business logic to be more lenient when deciding whether to accept addresses that the Address Validation API is not able to confirm.
For example, if you're in the US, you have the option to enable CASS™ from the United States Postal Service®1 in the Address Validation API response, which provides a high degree of detail on each address.
Many customers prefer to revalidate the addresses via a secondary process such as:
- Regulatory reasons mandate customers to guarantee the exact address being cached.
- If the initial call to validate the address fails, then revalidate the address offline.
We provide High Volume Address Validation as an open source software tool to implement address revalidation in a batch process.
Conclusion
The Address Validation API is a powerful tool to enhance the checkout experience for any ecommerce platform. Learn more about the Address Validation API and try it out here.
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.
Suggested further reading:
- Place Autocomplete Documentation
- Address Validation API Documentation
- Google Maps Platform Reporting
Contributors
Henrik Valve | Solutions Engineer
Thomas Anglaret | Solutions
Engineer
Sarthak Ganguly | Solutions
Engineer
-
Non-exclusive Licensee of the United States Postal Service. The following trademark(s) are owned by the United States Postal Service® and used with permission: CASS™, USPS®, DPV®. ↩
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2023-06-02 UTC.