Documentation

Understanding Location Data & Proximity Search

Last modified: June 25, 2026

Introduction

Gravity Search depends on a dedicated geolocation index layer to run distance, radius, and map-based queries efficiently. Gravity Search uses a dedicated location index to power distance calculations, proximity searches, and map-based queries.

If you are configuring search filters and result output, this page explains the behind-the-scenes geolocation pipeline that makes proximity work:
which fields are indexed, where data is saved, and how it is used when a visitor runs a location search.

Location Pipeline Overview

The location pipeline has three stages:

  1. Source data is selected on the Target Form.
  2. Entries are geocoded and synchronized into the shared location index.
  3. Search Forms query the indexed locations using selected “Location Source Fields”.

Target Form Configuration

Geocoding is configured on the Target Form (the form that stores the entries being searched).

1. Entry Geocoding Settings

In the target form settings, open:

Entry Geocoding section.

Enable Entry Geocoding

Turn this on to start geocoding selected fields on submission/update.

Fields to Geocode

Choose one or more source fields from the following supported types:

  • gfgeo_geocoder (preferred)
  • address
  • text
  • textarea

These fields are used to generate or carry geolocation data for each entry. At least one field is typically needed for meaningful proximity and map results.

Why field type matters

  • gfgeo_geocoder: Can provide a stored location payload directly when available.
  • address/text/textarea: Address-like values are geocoded during sync.
Gravity Search Entry Geocoding Settings

2. Import Existing Entry Locations

After setting field selection, use the importer to backfill locations for already-existing entries.

What it imports

  • Existing saved geocoder payloads for gfgeo_geocoder fields.
  • Existing address values for address/text/textarea fields (with geocoder requests as needed).

Important import behavior

The importer uses the current “Fields to Geocode” selection at the moment you start it.

  • Save target-form settings before importing.
  • Large imports may trigger API quota/rate-limiting for geocoding.
  • The importer reports per-field result and reason (imported / skipped / failed).

This is useful when enabling Search on an existing dataset that already has entries.

Existing entries are not indexed automatically when Entry Geocoding is first enabled. If you already have entries in your Target Form, the importer must be run before those entries can participate in proximity searches, distance calculations, and map displays.

See Importing Existing Entry Locations for step-by-step instructions.

Gravity Search Entry Geocoding Importer

When Locations Are Indexed

The indexer keeps location rows in sync with entry content.

  • On form submit: location indexing runs automatically.
  • On entry edit/update: indexed locations are refreshed.
  • On entry delete: related indexed locations are removed.

Indexed Location Storage

Indexed locations are stored in a dedicated location index maintained by WPGeo Framework.

Stored fields include

  • Coordinates: latitude, longitude
  • Address: address + formatted_address
  • Address parts: street, city, region, postcode, country, etc.
  • System fields: is_primary, title, place_id

Multiple locations per entry

Yes. If an entry has multiple geocoded fields selected, it can have multiple indexed rows.

Search queries can filter by one or more of those source field IDs. This allows different Search Forms to search different locations while using the same underlying dataset.

How Search Forms Consume Indexed Locations

This is configured in the Search Form under location-related settings (location scope/proximity section).

Location Data Scope

  • Location Source Fields: pick target-form field IDs whose indexed location rows should be queried.
  • These must match fields configured in the target form’s Fields to Geocode.
  • Source IDs are passed as source_object_ids into runtime location queries.

Proximity and map query behavior

  • If no source fields are selected, proximity/map features that require coordinates cannot operate.
  • Address-radius filters are applied against indexed rows, not raw entry values.
  • Hide Entries Without Location controls inclusion of location-less entries in map/filter scenarios.
  • When active proximity is requested, results are filtered against a valid radius and location join conditions.

3. How It Works Together

Conceptually:

  • Target form decides what gets indexed.
  • Searcher decides which indexed fields can be used at query time.
  • The match result is determined by both sides: indexed rows + query constraints.

Performance & Troubleshooting

Performance considerations

  • Keep unnecessary geocoded fields out of selection to reduce write workload.
  • Use tighter source field choices when you only need specific coordinates (e.g., business address only).
  • For existing large datasets, run the importer in controlled batches and monitor API usage.
  • Prefer gfgeo_geocoder where already available, to avoid repeated geocoding calls.

Common issues

  • No proximity results: no indexed source rows or missing/invalid geocoded fields.
  • Wrong distances: coordinates are missing/misaligned source field, wrong source selection, or stale index (re-sync/import).
  • Importer too slow / failures: API rate limits or malformed source values.
  • Unexpected missing matches: “Hide Entries Without Location” currently excludes no-location entries in strict modes.
menu-circle