Calculate routes between waypoint pins on a map (preview)
[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.
- 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)|
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:
Save the workbook to your OneDrive for Business and close the file.
Bind the data source to 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.
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.
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.
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.
Change how a route is calculated using properties.
|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|
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.
|OnRouteDirectionChange||Contains code that runs when the route is changed.||Event||Advanced|
|RouteDirection||Describes the routing outputs:
||Object||Not applicable (output property only)|
Submit and view feedback for