Insert waypoint pins and draw routes between them (preview)
[This topic is pre-release documentation and is subject to change.]
You can load a table that contains a dataset of waypoints into the map control. The control will then place pins on the map for each waypoint, and it can draw routes between the waypoints.
The control has options to reorder the waypoints or rearrange the route to improve travel time or travel 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.
Prerequisites
- Create a canvas app, and make sure it meets the Geospatial prerequisites.
- In your app, insert a map.
Add waypoint data from an Excel workbook
Your data source needs to contain a named table with the following columns that should then be mapped to the associated property in the control's Advanced pane.
| Column description | Maps to property | Required |
|---|---|---|
| Label for the waypoint | RouteWaypointsLabels | Optional |
| Longitude of the waypoint | RouteWaypointsLongitudes | Optional |
| Latitude of the waypoint | RouteWaypointsLatitudes | Optional |
| Address of the waypoint | RouteWaypointsAddresses | Optional |
Note
While all properties are optional, ensure one of the following conditions is met for the waypoint locations to be found:
- Address of the waypoint is required.
- Latitude and Longitude of the waypoint are required.
To get started, use an Excel workbook with a table similar to the sample shown below with the required columns:
You can copy the following sample data to test this functionality:
| Name | Longitude | Latitude |
|---|---|---|
| Work | -122.156481 | 47.663448 |
| Meet up | -122.221037 | 47.57137 |
| Swimming | -122.144133 | 47.600373 |
| Tennis | -122.137265 | 47.616115 |
After you have the Excel workbook created, follow the steps below to add waypoint data from this workbook.
Copy and paste the table into a new data source. In this example, we're using an Excel workbook.
Select one of the cells, and then on the Home tab in the ribbon, select Format as Table and choose any style, and then select OK.
Select the table, and then go to the Table Design tab on the ribbon.
Enter a name for the table under Table Name:. For example, TestData.
Save the workbook.
Open or create a new app in Power Apps, and insert the map control.
On the Properties pane, select the Route waypoints(Items) field and then search for excel and select Import from Excel.
Locate the Excel workbook, and then select Open.
Select the table that contains the information, TestData, and then Connect.
On the Properties pane, go to the Advanced tab.
Set the following properties:
Property Value RouteWaypointsLabels Name RouteWaypointsLatitudes Latitude RouteWaypointsLongitudes Longitude RouteWaypointsAddresses Address
NOTE: Optional, if your dataset has an address field. Address can be used in place of Latitude and Longitude in any rows where Latitude and Longitude aren't set.Note
Address is interchangeable with Latitude and Longitude. If Latitude and Longitude are provided, then Address will not be used. If only Address is provided, then Latitude and Longitude are not necessary.
The map control will now show each row in the table as a pin, labeled with its Name as defined in the Excel table, and numbered in the same order as the given dataset.
Draw routes between the waypoints
To draw routes between the waypoints on the map and customize how the route is calculated, you need to configure the following settings:
Open the Properties pane with a map selected.
Switch Enable routing to On.
The control will now draw routes between the waypoints on the map.
Note
By default, the control will reorder the middle waypoints to decrease travel time or travel distance. The first and last waypoints are considered the origin and destination and cannot be reordered. Waypoint order can be kept locked by switching the Maintain waypoint order toggle to On.
Properties
The following properties can configure how the route is calculated or:
| Property | Description | Type | Location |
|---|---|---|---|
| Enable routing | Whether routes are drawn between waypoints | Boolean | Properties (also in Advanced as UseRouting) |
| Maintain waypoint order | If true, the control will reorder the waypoints to optimize the route based on the Optimize route setting. If false, the control will maintain the order that the waypoints have in the dataset, and the Optimize route setting will only affect the drawn route. | Boolean | Properties (also in Advanced as RouteMaintainOrder) |
| Optimize route | Whether to optimize the route to decrease travel time or decrease travel distance. | Enumeration (None, Distance, Time) | Properties (also in Advanced as RouteOptimization) |
| Route travel mode | Whether the route will be traveled by car or by truck. | Enumeration (Car, Truck) | Properties (also in Advanced as RouteTravelMode) |
Output Properties
The control outputs various properties when the route changes. These properties are all placed in the RouteDirection object. The OnRouteDirectionChange event is a recommended way to use the output in other controls or to customize the experience.
| Property | Description | Type | Location |
|---|---|---|---|
| OnRouteDirectionChange | How the app responds when the route is changed | Event | Advanced |
| RouteDirection | Object describing all of the routing outputs:
|
Object | Not applicable (output property only) |