title | description | author | ms.topic | ms.custom | ms.reviewer | ms.date | ms.subservice | ms.author | search.audienceType | contributors | |||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Calculate routes between waypoint pins on a map (preview) |
Add waypoint pins to a map and calculate routes between them in Power Apps. |
anuitz |
conceptual |
canvas, ce06122020 |
mduelae |
3/3/2022 |
canvas-maker |
anuitz |
|
|
[!INCLUDEPreview disclaimer]
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.
- [!INCLUDEcc_preview_features_definition]
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.
In this example, we'll import waypoint data from an Excel table named TestData.
-
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:
:::image type="content" source="./media/geospatial/map-routing-table.png" alt-text="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.
-
Create a canvas app. Make sure it meets the geospatial prerequisites.
-
On the control's Properties tab, select the Route waypoints(Items) box and type excel.
:::image type="content" source="./media/geospatial/map-routing-property.png" alt-text="A screenshot that shows how to search for a waypoint data source to connect to a map control in Power Apps Studio.":::
-
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.
:::image type="content" source="./media/geospatial/select-table.png" alt-text="Screenshot of the table selection panel.":::
-
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.
:::image type="content" source="./media/geospatial/map-routing-pins.png" alt-text="A screenshot of a map with pinned and labeled waypoints shown next to the map's properties.":::
With the map control selected, open the Properties tab and turn on Enable routing.
The control calculates routes between the pinned waypoints.
:::image type="content" source="./media/geospatial/map-routing-directions.png" alt-text="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.
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 |
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:
|
Object | Not applicable (output property only) |