ConvertSite
Math functions

DRIVINGDURATION

Calculate the estimated driving time between two geographic coordinates.

Use DRIVINGDURATION when travel time matters: quoting jobs by how long the trip takes, scheduling appointments around drive time, or charging a callout or minimum-order fee for customers who are far away.

How it works

DRIVINGDURATION(lat1, lng1, lat2, lng2)
DRIVINGDURATION(lat1, lng1, lat2, lng2, unit)

  • lat1 - Latitude of the starting location (number between -90 and 90)

  • lng1 - Longitude of the starting location (number between -180 and 180)

  • lat2 - Latitude of the destination

  • lng2 - Longitude of the destination

  • unit - Optional. Unit for the result, in quotes. Defaults to seconds

Returns the driving time as a number in the specified unit.

DRIVINGDURATION works the same way as DRIVINGDISTANCE, and both use actual driving routes. The existing DISTANCE function only calculates straight-line distance.

How loading works

DRIVINGDURATION is the only FormulaScript function (together with DRIVINGDISTANCE) that fetches data over the network, so the first result for a coordinate pair is not instant.

  • The first time a formula runs with a coordinate pair it has not seen before, the result is empty for a moment while the route is retrieved in the background. The formula then runs again automatically and shows the result.

  • Coordinate pairs the formula has already used reuse the route that was retrieved before, so they calculate without waiting.

  • If a coordinate is not filled in yet (for example, the customer has not entered their address), the function returns 0 instead of an error.

Examples

Travel time to the customer

Calculate how many minutes the drive from your workshop to the customer takes.

WORKSHOP_LAT = 52.0907
WORKSHOP_LNG = 5.1214
TRAVEL_MINUTES = DRIVINGDURATION(WORKSHOP_LAT, WORKSHOP_LNG, CUSTOMER_LAT, CUSTOMER_LNG, "min")

Returns the driving time in minutes.

Add a travel-time surcharge to a quote

Charge an hourly rate for travel on top of the job price.

TRAVEL_HOURS = DRIVINGDURATION(OFFICE_LAT, OFFICE_LNG, CUSTOMER_LAT, CUSTOMER_LNG, "h")
QUOTE_TOTAL = JOB_PRICE + (TRAVEL_HOURS * HOURLY_RATE)

Calculates the quote including travel time.

Show the trip time on an appointment page

Display the estimated drive to the nearest branch.

TRAVEL_MINUTES = DRIVINGDURATION(CUSTOMER_LAT, CUSTOMER_LNG, BRANCH_LAT, BRANCH_LNG, "min")

Returns the driving time in minutes for the route to the branch.

Common mistakes

  • Swapping latitude and longitude - Latitude comes first, longitude second. Amsterdam is (52.37, 4.90) not (4.90, 52.37)

  • Reading the result as seconds when you asked for minutes - The default unit is seconds. Pass a unit to get a different result, for example "min"

  • Expecting a result on the first render - The first calculation for a new coordinate pair is empty until the route loads, then the formula runs again automatically

  • Forgetting unit quotes - Use "min" not min for the unit parameter

  • Using a distance or other non-time unit - A unit that is not a time unit produces a formula error

Understanding units

Common time units:

  • "s" - Seconds (default)

  • "min" - Minutes

  • "h" - Hours

DRIVINGDURATION also accepts any other time unit the CONVERT function supports. If the unit is not a time unit, the formula returns an error.

Errors

  • No drivable route - If no driving route exists between the two points, the formula returns the error "DRIVINGDURATION found no driving route between these points"

  • Invalid unit - A unit that is not a time unit produces a formula error naming the unit it could not convert to

Was this helpful?
Was this helpful?