Documentation

Directions Field

Last modified: September 26, 2026

Introduction

The Directions Field calculates travel between an origin Geocoder Field and a destination Geocoder Field. It can use Google Routes API for a road route, distance, estimated duration, and optional waypoints, or calculate a direct straight-line route and an approximate duration based on average travel speed.

Available in: Pro and Agency.

Routed directions require Routes API on the Browser API Key. Straight-Line (Haversine) calculations use coordinates already available in the form and do not require Routes API.

Each independent location needs its own Geocoder Field. Visitor-facing Address, Coordinates, Map, and Locator Button fields connect to those Geocoders; the Directions Field then uses the Geocoders as its route points.

Configuring the Directions Field

Travel Calculation Method

  • Google Routes API: Calculates a travel route, distance, and estimated duration using the selected route preferences.
  • Straight-Line (Haversine): Calculates the direct geographic distance between the route points. It does not follow roads; its duration is an estimate based on average speed for the selected travel mode rather than a Google road-route estimate.

Google Routes API is the default method.

Ninja Geolocation 3.5 retains a limited legacy compatibility fallback for certain existing forms when the Routes request specifically reports that Routes API is unavailable. Configure new forms for Routes API rather than relying on that fallback.

Directions Trigger Options

  • How Should Directions Be Triggered? Choose Manually (Using a Button) or Automatically (When Fields Change). Manual is the default.
  • Get Directions Button Text: Sets the manual calculation button label. The default is “Get directions.”
  • Clear Directions Button Text: Sets the button that clears the current result. The default is “Clear directions.”

Automatic mode recalculates when a connected location or linked travel option changes. Manual mode waits for the visitor to click the Get Directions button.

Directions Points

  • Origin Field (Geocoder): Select the starting location.
  • Destination Field (Geocoder): Select the ending location.
  • Waypoint Fields (Optional): Select one or more Geocoder Fields to place between the origin and destination.

Do not use the same Geocoder as both the origin and destination. Add another Geocoder Field for every independent route point.

Travel Options

  • Measurement System: Imperial (Miles) or Metric (Kilometers).
  • Travel Mode: Driving, Walking, Bicycling, Two-wheeler, or Transit.
  • Travel Mode Field: Optionally let the visitor choose the mode from a Dropdown or Radio List. Use choice values DRIVE, WALK, BICYCLE, TWO_WHEELER, or TRANSIT.
  • Routing Preference: Traffic Unaware (Shortest Distance), Traffic Aware, or Traffic Aware Optimal.
  • Avoid Ferries: Ask Google to avoid 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 all three options for every new Directions Field because they can produce a substantially longer route.

Google does not support every routing preference or avoidance option for every travel mode and region. The plugin omits unsupported routing-preference data where necessary.

Travel Date & Time Settings

  • Travel Time Mode: Leave Now, Leave At Specific Time, or Arrive At Specific Time.
  • Travel Time Mode Field: Optionally let the visitor choose the time mode from a frontend field. Use choice values now, departure, or arrival.
  • Default Travel Date: Sets the date used for a configured departure or arrival.
  • Travel Date Field: Optionally obtains the date from a frontend date field.
  • Default Travel Time: Sets the time used for a configured departure or arrival.
  • Travel Time Field: Optionally obtains the time from a frontend time field.

A connected frontend field overrides the corresponding default. When a departure or arrival time is used with Traffic Unaware, the runtime changes the request to Traffic Aware Optimal because a time-specific route requires traffic-aware routing.

Display Options

  • Map Field for Displaying Route: Select a Map Field in the same form to draw the route.
  • Polyline Appearance: Optionally customize the route line, for example strokeColor:'#0088FF',strokeWeight:6,strokeOpacity:0.6.
  • Directions Panel Output: Select a Directions Panel Field to display step-by-step route instructions.

The route map can also display a straight-line result. Step-by-step road instructions require a routed Google Routes API result.

Setting Up and Using the Directions Field

  1. Add one Geocoder Field for the origin.
  2. Add another Geocoder Field for the destination, plus a separate Geocoder for each optional waypoint.
  3. Add and connect the visitor-facing Address, Coordinates, Map, or Locator Button fields needed for each location.
  4. Add a Directions Field and select its origin, destination, and optional waypoints.
  5. Choose Google Routes API or Straight-Line (Haversine).
  6. Choose manual or automatic triggering.
  7. For Routes API, review the measurement system, travel mode, routing preference, date/time behavior, and all three avoid options.
  8. Optionally add a Map Field or Directions Panel Field and select it under Display Options.
  9. Save the form and test it with known locations and every visitor-selectable travel option.

Saved Value and Outputs

The Directions Field saves structured JSON containing the calculated travel result. To keep submissions manageable, the saved value omits large encoded polylines and detailed step geometry; the connected Map and Directions Panel use the live result while the form is running.

Geolocation merge-tag parts can request HTML, JSON, text, serialized or raw data, distance, duration, static duration, a directions link, or route legs.

Dynamic Field Options can copy these values into supported ordinary Ninja Forms fields:

  • 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 Directions Field as the source, and choose a numeric output. Use that Number field in the calculation.

Troubleshooting

No directions appear

Confirm that the origin and destination Geocoder Fields contain valid coordinates and that the Directions Field references the correct fields. In manual mode, the visitor must click Get Directions.

The route is much longer than expected

Review Avoid Ferries, Avoid Highways, and Avoid Tolls. All three are enabled in a newly added Directions Field, and avoiding one of these route types can significantly increase the distance.

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. Also test a supported combination of travel mode, routing preference, time mode, and avoid options.

The route map or instructions panel remains empty

Confirm that the intended Map Field and Directions Panel Field are selected under Display Options. The panel displays route steps only when the routed result supplies them; straight-line calculations do not provide turn-by-turn road instructions.

The distance is unavailable in a Ninja Forms calculation

Ninja Forms calculations do not read the structured Directions 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.

menu-circle