Understanding Location Data & Proximity Search
Introduction
Gravity Search uses a dedicated location index to perform proximity searches, distance calculations, and map queries efficiently.
The Target Form determines which entry fields are geocoded and indexed. Each Search then determines which of those indexed location sources it uses.
This guide explains how Target Form values become indexed locations and how Searches use those locations at runtime.
Location Pipeline Overview
The location pipeline has three main stages:
- The Target Form determines which entry fields should be geocoded.
- Location data from those fields is synchronized into the location index.
- Each Search selects which indexed Location Source Fields participate in proximity searches, distance calculations, results, and maps.
The Target Form collects and stores the entries. A Search queries those entries and their indexed locations but does not collect entries itself.
Configure Entry Geocoding
Entry geocoding is configured in the settings of the regular Gravity Form used as the Target Form.
Open the Target Form’s settings and locate the Entry Geocoding section.
1. Enable Entry Geocoding
Enable Entry Geocoding to index locations from selected fields when entries are submitted or updated.
2. Fields to Geocode
Select one or more Target Form fields whose values should be indexed as locations.
Supported field types include:
- Gravity Geolocation Geocoder
- Gravity Forms Address
- Single Line Text
- Paragraph Text
Geocoder Fields
A Geocoder field can supply its stored location payload directly when valid geocoded data is available.
Address and Text Fields
Address, Single Line Text, and Paragraph Text values are sent to the configured geocoding provider when coordinates need to be generated.
Only select fields that contain valid address or location values.
When Locations Are Indexed
Gravity Search keeps indexed location records synchronized with Target Form entries.
- Entry submission: Selected location fields are indexed when a new entry is created.
- Entry update: Indexed locations are refreshed when the entry or selected location values are updated.
- Entry deletion: Indexed locations associated with the deleted entry are removed.
New submissions and subsequent entry updates are handled automatically after Entry Geocoding has been enabled and the Fields to Geocode have been saved.
Existing Entry Locations
Enabling Entry Geocoding does not automatically process entries that already exist in the Target Form.
Use Import Existing Entry Locations to add those entries to the location index.
Before Starting the Import
- Enable Entry Geocoding.
- Select the appropriate Fields to Geocode.
- Save the Target Form settings.
- Confirm that any required geocoding-provider credentials and services are configured.
What the Importer Processes
- Stored location payloads from selected Geocoder fields.
- Address values from selected Address fields.
- Location values from selected text fields.
Geocoder fields may already contain usable coordinates. Address and text fields may require new requests to the configured geocoding provider.
Large imports can consume geocoding quota and may encounter provider rate limits. Run large imports in manageable batches and review skipped or failed records.
See Importing Existing Entry Locations for complete instructions.
Indexed Location Storage
Each indexed location is associated with its Target Form entry and source field.
Indexed location data can include:
- Latitude and longitude
- Entered and formatted addresses
- Street, city, region, postal code, and country components
- Place identifiers and other location metadata
Multiple Locations Per Entry
A single Target Form entry can contain multiple indexed locations when more than one field is selected under Fields to Geocode.
For example, an entry could contain:
- Home Location
- Work Location
- Warehouse Location
Different Searches connected to the same Target Form can use different combinations of these location sources.
How Searches Use Indexed Locations
After the Target Form locations have been indexed, open the Search’s Search Setup tab and locate Location Data Scope.
Location Source Fields
Select the Target Form fields whose indexed locations should be available to the Search.
The selected fields should correspond to fields enabled under the Target Form’s Fields to Geocode setting.
If no Location Source Field is selected, map and proximity controls that require coordinates remain unavailable.
Proximity Searches
When a visitor supplies an origin, Gravity Search compares that location with indexed rows from the selected Location Source Fields.
When a radius is applied, an entry qualifies when a selected indexed location falls within that distance of the origin.
Proximity filtering operates against indexed coordinates rather than repeatedly geocoding raw Target Form values during each search.
Maps
The Map uses indexed coordinates from matching entries to create result markers.
A map can display initial-load or predefined results without an active proximity search, provided the matching entries have indexed locations.
Hide Entries Without Location
Enable Hide Entries Without Location to exclude entries that do not have valid indexed data in any selected Location Source Field.
During an active proximity search, entries without usable location data cannot satisfy the distance query even when this setting is disabled.
Performance & Troubleshooting
Performance Recommendations
- Select only the Target Form fields that contain locations you actually need.
- Select only the Location Source Fields required by each Search.
- Use existing valid Geocoder payloads when available to avoid unnecessary geocoding requests.
- Run large existing-entry imports in manageable batches.
- Monitor the quota and rate limits of the configured geocoding provider.
Common Problems
- No proximity results: Confirm that Entry Geocoding is enabled, the correct Fields to Geocode are selected, and locations have been indexed.
- No map markers: Confirm that Location Source Fields are selected in Search Setup and that matching entries contain indexed locations.
- Incorrect distances: Verify the stored coordinates, selected location sources, search origin, radius, and units.
- Existing entries are missing: Run Import Existing Entry Locations after saving the Target Form’s Entry Geocoding settings.
- Import failures: Review malformed or empty address values and check the geocoding provider’s configuration, quota, and rate limits.
- Unexpected missing entries: Review Hide Entries Without Location and any active proximity radius.