Understanding Location Data & Proximity Search
Introduction
Gravity Search uses stored location records for proximity searches, distance calculations, result locations, and map markers.
The regular Gravity Form used as the Target Form determines which entry fields are currently synchronized as locations. Each Search then selects which eligible current or historical location sources it can use.
Location data is shared with other compatible Gravity Geolocation features. It is not a disposable Search-only copy, and selecting a source in Search settings does not create location records by itself.
Location Pipeline Overview
The location pipeline has three main stages:
- The Target Form identifies the entry fields that should currently be synchronized as locations.
- Valid coordinates and address data from those fields are stored as location records associated with the entry and source field.
- Each Search selects the Location Source Fields that may participate in proximity searches, distance calculations, results, and maps.
The Target Form collects and stores entries. A Search queries those entries and, when location scope is active, their qualifying stored location records. A Search does not collect or duplicate Target Form entries.
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 synchronize locations from selected fields when entries are submitted or updated.
2. Fields to Geocode
Select one or more Target Form fields whose current values should be synchronized as locations.
Supported source types include:
- Gravity Geolocation Geocoder
- Gravity Forms Address
- Single Line Text
- Paragraph Text
Geocoder Fields
A Geocoder field can supply its saved coordinates and location payload directly when valid data is available. Gravity Geolocation’s Geocoder field is optional; Gravity Search does not require it when another supported source or existing location records are 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. Select only fields that contain recognizable address or location values.
When Locations Synchronize
Gravity Search keeps the currently selected location sources synchronized with Target Form entries.
- Entry submission: Selected source fields are processed when a new entry is created.
- Entry update: The selected source’s stored location is updated when its current value produces valid coordinates.
- Source intentionally cleared: The location belonging to that entry and source field is removed without recording a geocoding failure.
- Current nonempty source cannot be geocoded: The stale location belonging to that source is removed and a diagnostic is recorded for the entry.
- Later successful update: The location is recreated and the related diagnostic is cleared.
- Entry deletion: Location records owned by the deleted entry are removed.
New submissions and later entry updates are handled automatically after Entry Geocoding and Fields to Geocode have been saved.
Existing & Historical Locations
Enabling Entry Geocoding affects new submissions and later updates. It does not automatically process entries that already exist in the Target Form.
Use Import Existing Entry Locations to synchronize locations for existing entries. Before starting, save the Target Form’s Entry Geocoding settings and confirm that any required geocoding-provider credentials and services are configured.
What the Importer Processes
- Valid stored coordinates and location payloads from selected Geocoder fields.
- Address values from selected Gravity Forms Address fields.
- Location values from selected text fields.
The importer includes a Geocode locations missing coordinates option. When enabled, address-only records can generate requests to the configured provider. Each request may count against the provider’s API quota and may incur charges. Disable the option to import only records that already contain coordinates.
Monitor large imports and review skipped or failed records. See Importing Existing Entry Locations for the complete procedure.
Historical Sources
Removing a field from Fields to Geocode, or disabling Entry Geocoding, stops future synchronization for that source. It does not automatically delete location records already created from that field.
Those historical records may remain useful to Gravity Search, maps, or other compatible location consumers. A Search can continue using an eligible historical source until its locations are explicitly removed or replaced.
Shared Location Storage
Each stored location is associated with its Target Form entry and source field. Depending on the source and provider response, a location can contain:
- Latitude and longitude
- Entered and formatted addresses
- Street, city, region, postal code, and country components
- Place identifiers and other location metadata
These records are canonical shared location data rather than Search-only copies. Disabling synchronization preserves existing records; clearing or failing an actively synchronized source follows the current-value rules described above.
Multiple Locations Per Entry
A single Target Form entry can own multiple locations when more than one source field has valid stored location data. For example, one entry might contain a Home Location, Work Location, and Warehouse Location.
Different Searches connected to the same Target Form can use different combinations of those sources.
When a Search has location scope, each qualifying location is a separate result identity. One entry can therefore appear multiple times with different addresses, distances, map markers, and positions in the result list. Result totals and pagination count those qualifying entry-location results rather than collapsing them into one entry.
How Searches Use Locations
Open the Search’s Search Setup tab and locate Location Data Scope to choose which eligible Target Form sources the Search may use.
Location Source Fields
The source picker can include eligible fields that are currently synchronized as well as historical sources with existing location data. Eligibility does not guarantee that the field is currently selected under Entry Geocoding or that every entry has a location record.
Selecting a Location Source Field scopes the records that the Search may use; it does not geocode entries or create locations. Use Entry Geocoding for new and updated entries and the importer for existing entries.
Location sources, proximity, and maps are optional. A Search can be ready without them. When a location-dependent feature is configured without a usable source, Search Readiness reports the dependency and links to the relevant settings.
Proximity Searches
When a visitor supplies an origin, Gravity Search compares its coordinates with qualifying records from the selected Location Source Fields. When a radius is applied, only locations within that distance qualify.
Proximity filtering uses stored coordinates. It does not repeatedly geocode every Target Form value during each search request.
Maps
The Map uses qualifying stored coordinates from the current result set to create markers. An entry with multiple qualifying locations can produce multiple markers.
A map can display Initial Load or predefined results without an active proximity search, provided those results contain qualifying locations from the selected sources.
Hide Entries Without Location
Enable Hide Entries Without Location to require each result to have valid location data from a selected Location Source Field.
During an active proximity search, a result without usable coordinates cannot satisfy the distance query even when this setting is disabled.
Performance & Troubleshooting
Configuration Recommendations
- Synchronize only Target Form fields that contain meaningful location values.
- Select only the Location Source Fields required by each Search.
- Reuse valid stored Geocoder coordinates when available to avoid unnecessary provider requests.
- Monitor large imports and the quota, rate limits, and billing rules of the configured geocoding provider.
- Use Search Readiness to identify saved configuration problems, then preview the Search to verify its actual entry and location data.
Common Problems
- No proximity results: Confirm that the Search has a selected Location Source Field with valid stored locations and that the search origin and radius are correct.
- No map markers: Confirm that the current results contain qualifying locations from the selected sources.
- Incorrect distances: Verify the stored coordinates, selected sources, search origin, radius, and units.
- Existing entries are missing locations: Save Entry Geocoding settings and run Import Existing Entry Locations.
- Import failures: Review empty or malformed source values and check the geocoding provider’s configuration, quota, rate limits, and billing status.
- A previously synchronized location disappeared: Check whether the current nonempty source failed to resolve and review the entry’s geocoding diagnostic.
- Unexpected missing results: Review Hide Entries Without Location, Location Data Scope, fixed filters, and any active proximity radius.