Documentation

Distance & Duration Field

Last modified: September 14, 2026

Introduction

The Distance & Duration Field in Gravity Geolocation calculates the distance and estimated travel time between two locations in a Gravity Form. It works with two Geocoder Fields: one provides the origin and the other provides the destination.

The field can calculate a road-based journey with the Google Routes API or a straight-line distance using the Haversine method. The result is saved with the Gravity Forms entry and can be displayed in entry details, exports, notifications, confirmations, or supported Gravity Forms fields.

Unlike the Directions Field, the Distance & Duration Field does not draw a route, use waypoints, or provide step-by-step directions. Use it when you need the distance and duration data without displaying a complete route.

Calculated distance and duration displayed in a Gravity Forms form

Display the calculated travel distance and duration between two locations.

Requirements

  • Add two Geocoder Fields to the form and configure each one with a location source, such as an Address Field or Coordinates Field.
  • Configure the Google Maps browser API key in the Gravity Geolocation settings.
  • Enable the Google Routes API when using the Google Routes API distance method.

The calculation begins only after both linked Geocoder Fields contain valid coordinates.

Configuring the Distance & Duration Field

Add the field from the Geolocation Fields group in the Gravity Forms editor, then configure the following settings.

Gravity Forms Distance and Duration Field settings

Configure the origin, destination, measurement system, travel mode, and routing preferences.

1. Distance Method

Choose how the distance and duration will be calculated:

  • Google Routes API: Calculates a road-based distance and travel duration using the selected travel mode and routing preferences (Default).
  • Straight-Line (Haversine): Calculates the direct distance between the two coordinates. The duration is an estimate based on average travel speed, not a road route.

2. Origin and Destination

Origin Geocoder

Select the Geocoder Field that supplies the starting location.

Destination Geocoder

Select the Geocoder Field that supplies the ending location.

The origin and destination must be different Geocoder Fields, and both fields must receive valid latitude and longitude coordinates before a calculation can run.

3. Measurement System

Choose how the human-readable distance is displayed:

  • Imperial (Miles) (Default).
  • Metric (Kilometers).

The complete saved result also contains the distance value in meters for consistent calculations and integrations.

4. Travel Mode

When using the Google Routes API, choose the method of travel:

  • Driving (Default).
  • Walking.
  • Bicycling.
  • Public Transit.

Travel mode and route availability can vary by location and by the data available from Google.

5. Routing Preference

For driving calculations, choose how traffic information should influence the result:

  • Traffic Unaware (Shortest Distance): Calculates without considering current traffic conditions (Default).
  • Traffic Aware: Uses traffic information when calculating the route.
  • Traffic Aware Optimal: Applies more comprehensive traffic-aware routing when supported.

6. Route Restrictions

Driving calculations can be configured to avoid:

  • Ferries.
  • Highways.
  • Toll roads.

These options express route preferences. A matching route is not guaranteed to be available.

7. Distance Failed Message

Enter the message shown when a road route cannot be calculated between the selected locations. The default message is No route could be found between the selected locations. Leave the setting empty if you do not want to show a message.

How the Calculation Works

  1. A location is selected or generated for each linked Geocoder Field.
  2. Once both locations contain valid coordinates, Gravity Geolocation automatically calculates the distance and duration.
  3. The complete result is saved in the hidden Distance & Duration Field.
  4. If either linked location changes, the field recalculates and saves the updated result.

The Distance & Duration Field itself is hidden on the front end because it acts as a calculation and storage field. To show a specific value to the user, populate a supported Gravity Forms field with the calculated data as described below.

Using the Calculated Data

Entry details and exports

The Gravity Forms entry detail page displays the saved distance, duration, origin, and destination. CSV exports use a readable distance and duration summary by default.

Populate another Gravity Forms field

Use a supported Gravity Forms field as a Dynamic Geolocation Field, select Distance Field as its usage, and link it to this Distance & Duration Field. You can populate any of the following values:

  • Distance text.
  • Distance numeric value.
  • Distance value in meters.
  • Duration text.
  • Duration value in seconds.

For example, populate a Gravity Forms Number Field with a numeric distance value and then use Gravity Forms' calculation settings to calculate a delivery fee. The Distance & Duration Field stores the travel result, but it is not itself a native Gravity Forms calculation field.

Merge tags

Use the field's Gravity Forms merge tag in confirmations and notifications. The field supports these output modifiers:

  • .html: formatted HTML output (Default).
  • .text: a plain-text distance and duration summary.
  • .distance: the human-readable distance.
  • .duration: the human-readable duration.
  • .json: the complete result as JSON.
  • .raw or .serialized: serialized result data for advanced integrations.

Add the modifier to the field ID portion of the merge tag. For example, if the field ID is 8, use {Distance & Duration:8.distance} for the distance text or {Distance & Duration:8.duration} for the duration text.

Setup Example

To calculate the driving distance between a pickup address and a delivery address:

  1. Add two Address Fields and two Geocoder Fields to the form.
  2. Link the first Geocoder Field to the pickup address and the second Geocoder Field to the delivery address.
  3. Add a Distance & Duration Field.
  4. Select the pickup Geocoder as the origin and the delivery Geocoder as the destination.
  5. Keep Google Routes API, Imperial, and Driving selected, or adjust them for your workflow.
  6. Preview the form, select both addresses, and submit a test entry.
  7. Open the entry and confirm that the distance, duration, origin, and destination were saved.

Troubleshooting

The field does not calculate

Confirm that both selected Geocoder Fields contain valid coordinates and that each is linked to the correct address or location input.

No road route is returned

Verify that the Google Routes API is enabled for the configured API key. Also test without route restrictions and confirm that the selected travel mode is available between the two locations.

The distance differs from a map application

Confirm the distance method, travel mode, unit system, routing preference, and route restrictions. Straight-line distance will not match a road route, and traffic-aware travel times can change.

The result is not visible in the form

This is expected. The Distance & Duration Field is hidden on the front end. Use a Dynamic Geolocation Field configuration to populate a visible supported field with the distance or duration value.

menu-circle