Skip to main content
All CollectionsAutomationFunctions
Function Route()
Function Route()

Use Route() to calculate traveling distance and time between any locations based on real-time and historic traffic and custom departure time

Sergey Shurygin avatar
Written by Sergey Shurygin
Updated over 2 years ago

Use Route() to get the traveling distance and time for a route with two or more locations. Use the function's parameters to indicate the traveling mode and control whether the route should account for real-time or historic traffic data, and avoid some types of roads.

How to use

Use the function in any of the following ways:

  • Route(lat1, lng1, lat2, lng2)

  • Route(lat1, lng1, lat2, lng2, params)

  • Route(waypoints)

  • Route(waypoints, params)

Input

  • lat1, lng1, lat2, lng2 (decimal or text): latitude and longitude coordinate (in Radians) of the starting and ending points of the route.
    ​

  • params: a json-array of any of the following routing parameters (all of them are optional except for some cases explicitly mentioned below):
    ​

    • travelMode (text): any of the following values (if omitted, Mapsly will use fastest):

      • fastest: fastest by car

      • shortest: shortest by car

      • truck_fastest

      • truck_balanced

      • bicycle

      • pedestrian
        ​

    • optimize (boolean): true (default, when omitted) or false. Applicable only if waypoints contain 4 or more points. When true, Mapsly will optimize the route by automatically re-ordering waypoints to minimize the total traveling time.
      ​

    • useTraffic (boolean): true or false (default, when omitted). When true, Mapsly will account for traffic when building the route:
      ​

      • if the startAt parameter is omitted, Masply will user the current (real-time) traffic data;
        ​

      • if the startAt parameter is present, Mapsly will use historic traffic data to forecast traffic at the indicated day and time.
        ​

    • startAt (datetime or text): the departure date and time. Applicable only when useTraffic is true. You may indicate it in either of the two formats:
      ​

      • as a stadard datetime value that includes the timezone:
        ​2010-04-27T12:00:00+02:00. To set a departure time based on the current date and time, use the Now() function with the Twig date_modify filter.
        ​

      • or as the local time at the route's starting location in the YYYY-MM-DD HH:MM format.
        ​

    • avoid: a json-array of road types that should be avoided. A road type can be any of the following values: tunnel, dirtRoad, boatFerry, railFerry, motorway, tollroad. This is presumed to be a "soft" requirement: if there's no alternative route that avoids these types of roads, Mapsly may return a route that includes them.
      ​

  • waypoints: a json-array of coordinates containing the route waypoints. Just like a route in the Mapsly user interface, when you're building an optimized route with automatic waypoints sequencing (optimize is true), waypoints may contain up to 25 points; if you don't require waypoints sequencing (optimize is false), waypoints may contain up to 50 points.
    ​
    Example value: [{"lat": 52.267700, "lng": 21.060480}, {"lat": 52.201282, "lng": 20.840765}]
    ​
    ​Note. When optimize is true, the first and last poinst in waypoints are not re-shuffled, as they are considered the starting and finishing locations of the route (just like when building a route in the Mapsly user interface).

Output

The function returns an object with the following fields:

  • success (boolean): true if the route has been built successfully or false if it hasn't been
    ​

  • message (text): a readable message describing why the route hasn't been built. Present only if success is false.
    ​

  • distance_km (decimal): the route's traveling distance in kilometers
    ​

  • distance_mi (decimal): the route's traveling distance in miles
    ​

  • time (decimal): the route's traveling time in minutes

Example

  • Route(37.78570, -122.40106, record.mapsly_geo_lat, record.mapsly_geo_lng).distance_mi - returns the driving distance from the San Francisco Museum of Modern Art to the current record's location, with no account for traffic.
    ​

  • Route("37.78570", "-122.40106", record.mapsly_geo_lat, record.mapsly_geo_lng, {"useTraffic": true; "startAt": Now()|date_modify("+1 day")}).time - returns the driving time from the San Francisco Museum of Modern Art to the current record's location based on the traffic usual for the current time of the day on the next day from today.
    ​

  • Route([{lat: 37.78570, lng: -122.40106}, {lat: record.mapsly_geo_lat, lng: record.mapsly_geo_lng}], {useTraffic: true, travelMode: "bicycle"}).time - returns the cycling time from the San Francisco Museum of Modern Art to the current record's location based on the current traffic.

See also

  • CurrentRoute() - get the traveling distance and time between the base record and the current match candidate (when used in a 'Match record' action's Rating formula) or the matched record (when used in 'Match record' action's Match actions) without explicitly specifying coordinate fields.
    ​

  • DirectDistance() - get the direct distance between any two locations in your Mapsly org's distance units
    ​

  • CurrentDirectDistance() - get the direct distance between the base record and the match candidate (when used in a 'Match record' action's Rating formula) or the matched record (when used in 'Match record' action's Match actions) without explicitly specifying coordinate fields.
    ​

  • Geocode() - get the coordinates of an address, as well as cleansed address (with corrected typos and filled in missing components like zip code or county).
    ​

  • How to use Mapsly functions

Did this answer your question?