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)


  • 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).


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


  • 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

Did this answer your question?