Calculate routes between waypoint pins on a map (preview)

Article
07/15/2022

[This topic is pre-release documentation and is subject to change.]

The map control in a canvas app can add waypoint pins using data imported from a table in an Excel workbook. The control can calculate routes between waypoints, reorder waypoints, and recalculate a route to improve travel time or distance.

Important

This is a preview feature.
Preview features aren’t meant for production use and may have restricted functionality. These features are available before an official release so that customers can get early access and provide feedback.

You'll need a data source that contains a named table with the following columns. Each column corresponds to an advanced property of the map control. Each row is pinned as a waypoint on the map.

Column name	Corresponds to	Required
Name (or Label)	RouteWaypointsLabels	Optional
Longitude	RouteWaypointsLongitudes	Optional (required if Address isn't given)
Latitude	RouteWaypointsLatitudes	Optional (required if Address isn't given)
Address	RouteWaypointsAddresses	Optional (required if Longitude and Latitude aren't given)

Note

All properties are technically optional. However, at least one of an address or a latitude/longitude pair must be provided for the waypoint location to be plotted.

Import waypoint pins from an Excel table

In this example, we'll import waypoint data from an Excel table named TestData.

Create a data source

Create a table in Excel with the following data. Name the table TestData.

Name	Longitude	Latitude	Address
Work	-122.156481	47.663448	1 Microsoft Way, Redmond, WA 98052
Meet up	-122.221037	47.57137
Swimming	-122.144133	47.600373
Tennis	-122.137265	47.616115

Your table should look something like this:

An example Excel worksheet with a table named TestData that contains information needed to place waypoint pins on a map.

Save the workbook to your OneDrive for Business and close the file.

Bind the data source to a map control

Create a canvas app. Make sure it meets the geospatial prerequisites.
Insert a map control.
On the control's Properties tab, select the Route waypoints(Items) box and type excel.
Select Import from Excel.
Navigate to your OneDrive for Business and select the Excel workbook you saved earlier.
Select the table TestData, and then select Connect.
On the Advanced tab, find RouteWaypointsLabels, RouteWaypointsLatitudes, RouteWaypointsLongitudes, and RouteWaypointsAddresses and enter the name of the corresponding column in the table. (In this example, enter Name in RouteWaypointsLabels, Latitude in RouteWaypointsLatitudes, and so on.) Enclose the column name in quotation marks.

Note

Address is interchangeable with Latitude and Longitude. If Latitude and Longitude are provided, then Address isn't used. If Address is provided, then Latitude and Longitude aren't needed. There is a limit to the number of waypoints that can be displayed when using address, so use Latitude and Longitude when possible.

Pins appear on the map at the locations described by the coordinates or addresses in the table. If the table included labels, the pins are labeled. The pins are numbered in the order the waypoint locations appear in the table.

A screenshot of a map with pinned and labeled waypoints shown next to the map's properties.

Calculate routes between the waypoints

With the map control selected, open the Properties tab and turn on Enable routing.

The control calculates routes between the pinned waypoints.

A screenshot of a map with routes between pinned waypoints.

Note

By default, the map control reorders the middle waypoints to decrease travel time or travel distance. The first and last waypoints are considered the origin and destination and can't be reordered. To keep the waypoints in the order given in the data source, turn on the control's Maintain waypoint order property.

Properties

Change how a route is calculated using properties.

Property	Description	Type	Tab
Enable routing	Calculates routes between waypoints.	Boolean	Properties; Advanced: UseRouting
Maintain waypoint order	Determines whether a calculated route maintains waypoints in the order provided in the data source.	Boolean	Properties; Advanced: RouteMaintainOrder
Optimize route	Determines whether a calculated route is optimized for distance, time, or isn't optimized.	Dropdown list	Properties; Advanced: RouteOptimization
Route travel mode	Determines whether a route is calculated for a car or a truck, which may require avoiding bridges with certain height or weight restrictions.	Dropdown list	Properties; Advanced: RouteTravelMode
Show route pins	Determines whether pins are shown over the route waypoints.	Boolean	Properties; Advanced: ShowRoutePins

Output Properties

Some properties become available only when a calculated route changes. These output properties are placed in the RouteDirection object. The OnRouteDirectionChange event is a recommended way to use the output in other controls or to customize the app experience.

Property	Description	Type	Tab
OnRouteDirectionChange	Contains code that runs when the route is changed.	Event	Advanced
RouteDirection	Describes the routing outputs: LengthInMeters: The length in meters of the entire route TravelTimeInSeconds: The expected travel time in seconds of the entire route RouteGeoJSON: A string that describes the route in GeoJSON format RouteLegs: A table that describes each leg of the route: Index: A number that represents the leg's order in the route LengthInMeters: The length of the leg in meters TravelTimeInSeconds: The expected travel time of the leg in seconds StartLabel: The label of the leg's starting point StartLatitude: The latitude of the leg's starting point StartLongitude: The longitude of the leg's starting point StartAddress: The address of the leg's starting point EndLabel: The label of the leg's ending point EndLatitude: The latitude of the leg's ending point EndLongitude: The longitude of the leg's ending point EndAddress: The address of the leg's ending point OrderedWaypoints: A table that describes each waypoint after the waypoints are ordered: Index: A number that represents the waypoint's order in the route Label: The label of the waypoint Latitude: The latitude of the waypoint Longitude: The longitude of the waypoint Address: The address of the waypoint	Object	Not applicable (output property only)

Share via