Distance & Duration Field
Introduction
The Distance & Duration Field calculates the distance and duration between an origin Geocoder Field and a destination Geocoder Field. It can calculate a road route and estimated travel time through Google Routes API, or a direct straight-line distance with an approximate duration based on average travel speed.
Available in: Pro and Agency.
Route calculations require Routes API to be enabled on the Browser API Key. Straight-Line (Haversine) calculations use coordinates already available in the form and do not require Routes API.
The field works in the background and is hidden on the frontend. Use an Address, Coordinates, Map, or Locator Button field connected to each Geocoder when visitors need to provide or view the origin and destination.
Configuring the Distance & Duration Field
Travel Calculation Method
- Google Routes API: Calculates a travel route, distance, and estimated duration using the selected travel preferences.
- Straight-Line (Haversine): Calculates the direct geographic distance between the two coordinate pairs and estimates duration from an average speed for the selected travel mode. It does not follow roads or provide a Google road-travel time.
Google Routes API is the default method.
Origin and Destination
- Origin Field (Geocoder): Select the Geocoder Field containing the starting location.
- Destination Field (Geocoder): Select the Geocoder Field containing the ending location.
Each independent location needs its own Geocoder Field. Do not select the same Geocoder as both the origin and destination.
Travel Preferences
- Measurement System: Imperial (Miles) or Metric (Kilometers).
- Travel Mode: Driving, Walking, Bicycling, Two-wheeler, or Transit.
- Routing Preference: Traffic Unaware (Shortest Distance), Traffic Aware, or Traffic Aware Optimal.
- Avoid Ferries: Ask Google to avoid routes that include ferries where supported.
- Avoid Highways: Ask Google to avoid highways where supported.
- Avoid Tolls: Ask Google to avoid toll roads where supported.
The shipped field defaults use Imperial units, Driving, and Traffic Unaware. Avoid Ferries, Avoid Highways, and Avoid Tolls are also enabled by default. Review these three options for every new field because they can produce a substantially longer route.
Some routing preferences and avoid options are not supported for every travel mode or region. Google may ignore or reject an unsupported combination.
Error Handling
Distance Failed Message controls the message displayed when a route cannot be calculated. The default message is “No route could be found between the selected locations.” Leave it empty to suppress the message.
Setting Up and Using the Distance & Duration Field
- Add one Geocoder Field for the origin.
- Add a second Geocoder Field for the destination.
- Add and connect the visitor-facing Address, Coordinates, Map, or Locator Button fields needed for each location.
- Add a Distance & Duration Field.
- Select the Origin Field (Geocoder) and Destination Field (Geocoder).
- Choose Google Routes API or Straight-Line (Haversine).
- If using Routes API, review the measurement system, travel mode, routing preference, and all three avoid options.
- Save the form and test it with two known locations.
Use the Directions Field instead when the form also needs waypoints, travel date/time settings, a route drawn on a Map Field, or turn-by-turn instructions in a Directions Panel.
Saved Value and Outputs
The field saves structured JSON containing the origin, destination, route condition, distance, and duration data available for the calculation.
Its readable submission and merge-tag output presents the calculated result. Geolocation merge-tag parts can also request HTML, JSON, text, serialized or raw data, distance, or duration.
When Straight-Line (Haversine) is selected, duration outputs are approximate values derived from average travel speed rather than Google route or traffic data.
Ordinary Ninja Forms fields can dynamically receive the following Distance & Duration values:
- Distance text.
- Numeric distance in the selected measurement system.
- Distance in meters.
- Duration text.
- Duration in seconds.
To use distance or duration in a Ninja Forms calculation, add a Number field, enable its Dynamic Field Options, select the Distance & Duration Field as the source, and choose a numeric output. Use that Number field in the calculation.
Troubleshooting
No calculation appears
Confirm that both Geocoder Fields contain valid latitude and longitude values and that the Distance & Duration Field is connected to the correct origin and destination fields. Entering text without resolving the location may not supply coordinates.
The route is much longer than expected
Review Avoid Ferries, Avoid Highways, and Avoid Tolls. All three are enabled in a newly added field, and avoiding one of these route types can significantly increase the distance.
No route can be found
Try a supported travel mode, turn off unnecessary avoid options, and confirm that a routable connection exists. Straight-Line (Haversine) can still calculate direct distance when no road route exists.
Routes API returns an error
Confirm that Routes API and billing are enabled, the Browser API Key permits Routes API, and the key's HTTP-referrer restrictions include the site where the form is displayed.
The distance is unavailable in a Ninja Forms calculation
Ninja Forms calculations do not read the structured Distance & Duration value directly in version 3.5. Dynamically populate a Number field with Numeric Distance, Distance in Meters, or Duration in Seconds, then use that Number field in the calculation.