Documentation

Nearest Locations Field

Last modified: September 14, 2026

The Nearest Locations Field finds nearby destination records from a visitor's origin, displays the results on a map, and saves the selected location with the Gravity Forms entry. Destinations can be entered manually or loaded from a database table, filtered by straight-line distance, and optionally refined with Google Routes API travel distance and duration.

Table of Contents

Nearest Locations Field Overview

The field uses a linked Geocoder Field as the search origin. It compares that position with a configured list of destinations, orders eligible results by distance, and lets the visitor select one location. The selection can populate other Geocoder Fields, highlight a marker, appear in a dedicated Nearest Locations Panel, populate Dynamic Fields, and be stored with the entry.

Nearest Locations Field displaying nearby destinations on a Gravity Forms map

Find and select the nearest eligible destination from the form’s map.

Required and Optional Fields

  • Required: A Geocoder Field that supplies the origin coordinates.
  • Optional: A Map Field for destination markers.
  • Optional: A Nearest Locations Panel Field for the selected-location summary.
  • Optional: One or more output Geocoder Fields that should receive the selected destination.

Nearest Locations Field Settings

1. Trigger Method

Choose Manually (Using a Button) to show Get Locations and Clear Locations controls, or Automatically (When Fields Change) to rerun the search when the connected location data changes. Button labels are customizable for manual mode.

2. Origin Field (Geocoder)

Select the Geocoder Field that contains the visitor's or starting location. The search cannot run until that field has valid latitude and longitude values.

3. Locations Source

Choose Manual Locations to enter destination records in the field settings or Database Table to query a table on the current WordPress site. Set the latitude and longitude key or column names used by the chosen source.

4. Results Limit, Search Radius, and Units

Limit how many results are displayed, optionally exclude destinations outside a radius, and choose miles or kilometers. Leaving the radius empty applies no radius limit.

5. Map Display

Select a Map Field to show result markers. You can provide default and selected marker icon URLs, enable marker clustering, choose whether a marker click immediately selects its location, and customize the marker info-window HTML.

6. Output Display

Select a Nearest Locations Panel Field, create the selected-location output template, and choose whether the nearest result should display automatically. Templates accept location properties such as {title}, {address}, and {distance}.

7. Output Geocoder Fields

Select one or more Geocoder Fields that should receive the destination chosen by the visitor.

8. Routes API Matrix

Enable matrix calculations to refine nearby candidates using Google Routes API travel distance and duration. Configure the matrix location limit, preselection threshold, travel mode, and route options for avoiding ferries, highways, or tolls.

Nearest Locations Field Matrix API and distance settings

Configure result limits, distance thresholds, travel mode, and Matrix API options.

Location Source Formats

Manual Locations

Enter one destination per line using pipe-separated key/value pairs, CSV, or JSON. Coordinates are required and the coordinate keys must match the Latitude Column and Longitude Column settings. Other values such as title, address, category, note, or icon may be included for templates and saved output.

latitude:40.7128 | longitude:-74.0060 | address:New York, NY | title:Office
latitude:47.6062 | longitude:-122.3321 | address:Seattle, WA | title:Support Center

Database Table

Enter a valid table name and the columns that contain latitude and longitude. This is an advanced source intended for an existing table on the WordPress database. The server resolves the form's saved configuration; visitors do not choose the table or columns.

Straight-Line and Routes API Results

Every search can use Haversine straight-line distance to find and pre-sort nearby destinations. When Use Matrix API is enabled, the field sends the top eligible candidates to the Google Routes API to obtain route-aware distance and duration. The matrix threshold limits which straight-line candidates are sent, and the matrix limit caps the request at 25 locations.

If route-matrix data is unavailable, the field preserves the straight-line results and reports the matrix problem rather than discarding the entire nearest-location search.

Selection, Saved Data, and Merge Tags

Selecting a result saves that location and its calculated values, updates linked output fields, and changes the selected marker when configured. Entry details display the selected location.

The default merge tag returns formatted HTML. Available modifiers include html, text, json, distance, duration, address, or any saved location key such as title. For example, {Nearest Location:10.distance} returns the formatted distance for field 10.

Basic Setup

  1. Add an origin Geocoder Field and connect it to the address or map inputs used by the visitor.
  2. Add the Nearest Locations Field and select the origin Geocoder Field.
  3. Choose Manual Locations or Database Table and configure valid destination coordinates.
  4. Set the result limit, optional radius, and measurement system.
  5. Optionally add and connect a Map Field, Nearest Locations Panel, and output Geocoder Fields.
  6. Enable Routes API Matrix only when route-aware distances or durations are needed.
  7. Save and test searches from several origins, including a location with no result inside the radius.

Troubleshooting

  • No search runs: Verify that the origin Geocoder Field has numeric latitude and longitude values.
  • Manual destinations are ignored: Make sure every record has coordinate keys matching the Latitude Column and Longitude Column settings.
  • A database source fails: Verify the table and column names and confirm that the database user can read the table.
  • Markers do not appear: Select a Map Field and confirm that the destination coordinates are valid.
  • Matrix results are unavailable: Enable the Google Routes API for the applicable API key and verify its restrictions. Straight-line results can still be used.
menu-circle