Documentation

Address Validation Field

Last modified: September 14, 2026

The Address Validation Field checks an address supplied by a linked Geocoder Field and presents a clear review step when the address needs confirmation or correction. It can save the selected address and validation metadata with the Gravity Forms entry, send the confirmed address to another Geocoder Field, and expose validation details to conditional logic, Dynamic Fields, merge tags, notifications, and confirmations.

Table of Contents

Address Validation Field Overview

The field works with a Geocoder Field that contains the address to validate. When that address changes, Gravity Geolocation sends it to the Google Address Validation service. Depending on the response, the field can confirm the address, show a suggested standardized address, let the user keep the original address, or ask the user to make changes.

The visible review panel appears only when it is needed. The value saved with the entry is a structured validation record that can include the submitted address, suggested address, selected address, selection type, status, outcome, delivery status, messages, and provider response details.

Address validation review showing the entered and recommended address in Gravity Forms

Review the entered and recommended address before confirming the final selection.

Before You Start

  • Add and configure a Geocoder Field in the same form.
  • Make sure the linked Geocoder Field receives a complete address from an Address Field, autocomplete field, map, coordinates, or another supported location input.
  • Configure a Google Maps browser API key and enable the Google Address Validation API for that key. See Google Maps API Keys.

Address Validation Field Settings

1. Geocoder Field

Select the Geocoder Field whose address should be validated. This is the source address for the validation request.

2. Output Geocoder Field (optional)

Select a second Geocoder Field if the confirmed or selected address should be copied to another location record. Choose None to keep the selection in the Address Validation Field only.

3. USPS Policy (US only)

Controls how USPS delivery-point signals affect US and Puerto Rico address validation.

  • Off: Ignore USPS-specific delivery information.
  • Notes Only: Show USPS delivery notes without making them a strict requirement.
  • Strict: Treat an unconfirmed USPS delivery point or an explicit non-delivery signal as an address that needs correction.
  • Strict + Fail Unknown: Apply strict checks and also require correction when USPS cannot provide a delivery-point result.

4. Auto-Apply Suggested Address

Automatically accept Google's standardized suggestion when one is available. Leave this disabled when users should compare the original and suggested addresses before confirming.

5. Standard Gravity Forms Settings

Use the standard label, description, visibility, CSS class, conditional logic, default-value, and custom-field options as needed. The field supports conditional logic and can also be used as a source for the Dynamic Geolocation Field.

Gravity Forms Address Validation Field settings

Choose the source and optional output Geocoder Fields for address validation.

USPS policy options for the Gravity Forms Address Validation Field

Choose how USPS delivery-point information affects address validation.

Front-End Validation Workflow

  1. The linked Geocoder Field receives an address.
  2. The Address Validation Field checks the address with Google's Address Validation service.
  3. If the address is already confirmed, the field saves the confirmed result without interrupting the form.
  4. If a standardized suggestion or correction is available, the panel lets the user choose the original address, accept the suggestion, or return to the form to make changes.
  5. The selected address and validation metadata are saved with the entry. If an Output Geocoder Field is selected, it receives the confirmed address as well.

Saved Data and Merge Tags

The field's normal merge tag returns the selected address. Add a modifier to request another part of the saved validation record:

  • selected returns the final selected address.
  • suggested returns the standardized suggested address, when available.
  • status returns the validation status.
  • outcome returns the validation outcome.
  • delivery_status returns the saved delivery status.
  • html returns a formatted summary.
  • json returns the complete saved validation payload.

For example, select the field's merge tag in Gravity Forms and append the needed modifier to its field ID, such as {Address Validation:8.status}. Replace 8 with the actual field ID.

Basic Setup

  1. Add an Address Field and a Geocoder Field to the form, then link the Address Field to the Geocoder Field.
  2. Add the Address Validation Field.
  3. Select the Geocoder Field as the source.
  4. Optionally select a different Geocoder Field to receive the confirmed address.
  5. Choose the USPS policy and whether suggestions should be applied automatically.
  6. Save the form and test a complete address, an address with a standardization suggestion, and an incomplete address.

Troubleshooting

  • No validation occurs: Confirm that the source Geocoder Field is selected, contains coordinates and address data, and changes on the front end.
  • An API error appears: Confirm that the browser API key is valid for the site and that the Address Validation API is enabled in the same Google Cloud project.
  • The confirmed address does not populate another field: Select the correct Output Geocoder Field and verify that it is not the same field used as the source.
  • USPS results are missing: USPS delivery signals apply only when Google returns supported US or Puerto Rico postal data. Use Notes Only unless strict delivery verification is required.
menu-circle