Nearest Locations Field

Introduction

The Nearest Locations Field compares an origin from a Geocoder Field with a configured set of destinations. It can filter and order nearby results, display them on a Map or in a Nearest Locations Panel, and copy the visitor's selected destination into other Geocoder Fields.

Available in: Agency.

Basic proximity uses straight-line distance between coordinates and does not require Routes API. Optional travel-distance refinement uses Routes API: manual destination sources use the Browser API Key, while database sources use the Server API Key. A connected Map Field requires Maps JavaScript API.

Configuring the Nearest Locations Field

Behavior & Trigger

• Trigger Method: Run Manually (Using a Button), or Automatically (When Fields Change).
• Get Locations Button Text: Customize the manual search button. The default is “Get Locations.”
• Clear Locations Button Text: Customize the clear button. The default is “Clear Locations.”

Origin and Destination Source

Origin Field (Geocoder) selects the visitor or form location used as the starting point.

Locations Source can use Manual Locations or a Database Table.

Manual Locations

Every destination needs numeric latitude and longitude values. An address and any custom properties—such as title, category, or notes—can also be used in templates and dynamic outputs.

Use one of the following formats:

Pipe-delimited rows

latitude:40.7128 | longitude:-74.0060 | address:New York, NY | title:Downtown Office

CSV

latitude,longitude,address,title
40.7128,-74.0060,"New York, NY","Downtown Office"
34.0522,-118.2437,"Los Angeles, CA","West Office"

JSON

[
  {"latitude":40.7128,"longitude":-74.0060,"address":"New York, NY","title":"Downtown Office"},
  {"latitude":34.0522,"longitude":-118.2437,"address":"Los Angeles, CA","title":"West Office"}
]

If the source uses different coordinate key names, enter those exact names in Latitude Column and Longitude Column.

Database Table

Enter the Database Table Name and the exact Latitude Column and Longitude Column names. The saved configuration is resolved and signed by the server; public requests cannot provide arbitrary table or column names.

Use a database source only when you understand the table schema. Developers can control additional output columns through the plugin's server-side filters.

Results & Calculations

• Results Limit: Maximum nearby results returned to the form. The default is 25.
• Search Radius: Optional maximum distance from the origin. Leave empty for no radius limit.
• Measurement System: Imperial (Miles) or Metric (Kilometers).

Map Display

Select a Map Field for Displaying Results to show destination markers. Optional settings include:

• Default Marker Icon URL and Selected Marker Icon URL.
• Enable Marker Clustering, which is enabled by default.
• Select Location on Marker Click.
• Info Window Template, which can use destination properties such as {title}, {address}, and {distance}.

Output Display and Geocoders

• Nearest Locations Panel: Select the visual panel that will display the selected destination.
• Nearest Location Output Template: Define the panel markup using destination-property placeholders.
• Auto Display Nearest Location: Automatically select and display the nearest result after a search. This is enabled by default. A Results Limit of 1 also automatically applies the single nearest result.
• Output Geocoder Fields: Select one or more Geocoder Fields that should receive the chosen destination and update their connected fields.

Travel-Distance Refinement

Basic results are found and ordered by straight-line distance. Enable Use Matrix API in the Advanced (Matrix API) settings to refine a limited candidate set using Google travel distance and duration through Routes API.

• Matrix Locations Limit: Maximum candidates sent for route refinement. The default is 15; the server enforces a maximum of 25.
• Matrix Distance Threshold: Only straight-line candidates within this distance are refined. The default is 50 in the selected measurement system.
• Travel Mode: Driving, Walking, Bicycling, or Two Wheeler.
• Avoid Ferries, Avoid Highways, and Avoid Tolls: Route modifiers used where supported. All three are enabled by default in a newly added field.

Manual-location refinement runs in the browser and uses the Browser API Key. Database-source refinement runs on the server and uses the Server API Key. If refinement is unavailable, the field can continue using straight-line results.

Setting Up and Using the Nearest Locations Field

1. Add a Geocoder Field for the visitor's origin.
2. Add and connect an Address, Coordinates, Map, or Locator Button field for entering the origin as needed.
3. Add a Nearest Locations Field and select the Origin Field (Geocoder).
4. Choose Manual Locations or Database Table and configure the destination source.
5. Set the results limit, optional search radius, and measurement system.
6. Optionally add a Map Field and select it under Map Field for Displaying Results.
7. Optionally add a Nearest Locations Panel, select it in the Nearest Locations Field, and customize the output template.
8. Optionally select Output Geocoder Fields that should receive the chosen destination.
9. Enable travel-distance refinement only when the workflow needs road distance or duration, then review its limit, threshold, mode, and avoid options.
10. Save the form and test searching and selecting a known destination on the frontend.

Saved Value and Outputs

The field saves the complete selected-result object as structured JSON. It can include the selected destination, location data, straight-line or refined distance, duration when available, and custom source properties.

Ninja Geolocation provides readable submission and merge-tag output. Geolocation merge-tag parts can request HTML, JSON, text, distance, duration, address, or title.

Dynamic Field Options can copy a built-in value or a custom destination property into a supported ordinary Ninja Forms field. Output Geocoder Fields receive the selected destination as a synchronized location.

The Nearest Locations Panel does not save a separate value; use the Nearest Locations Field for submission data, notifications, merge tags, and integrations.

Troubleshooting

Helpful Links

• Nearest Locations Panel Field
• Geocoder Field
• Google Map Field
• Dynamic Geolocation Field Options
• Google Maps API Keys