You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/azure-maps/how-to-use-best-practices-for-routing.md
+32-28Lines changed: 32 additions & 28 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,7 +12,7 @@ services: azure-maps
12
12
13
13
# Best practices for Azure Maps Route service
14
14
15
-
The Route Directions and Route Matrix APIs in Azure Maps [Route service] can be used to calculate the estimated arrival times (ETAs) for each requested route. Route APIs consider factors such as real-time traffic information and historic traffic data, like the typical road speeds on the requested day of the week and time of day. The APIs return the shortest or fastest routes available to multiple destinations at a time in sequence or in optimized order, based on time or distance. Users can also request specialized routes and details for walkers, bicyclists, and commercial vehicles like trucks. In this article, we'll share the best practices to call Azure Maps [Route service], and you'll learn how-to:
15
+
The Route Directions and Route Matrix APIs in Azure Maps [Route service] can be used to calculate the estimated arrival times (ETAs) for each requested route. Route APIs consider factors such as real-time traffic information and historic traffic data, like the typical road speeds on the requested date and time. The APIs return the shortest or fastest routes available to multiple destinations at a time in sequence or in optimized order, based on time or distance. Users can also request specialized routes and details for walkers, bicyclists, and commercial vehicles like trucks. This article discusses best practices for calling the Azure Maps [Route service], including how-to:
16
16
17
17
* Choose between the Route Directions APIs and the Matrix Routing API
18
18
* Request historic and predicted travel times, based on real-time and historical traffic data
@@ -35,7 +35,7 @@ This article uses the [Postman] application to build REST calls, but you can cho
35
35
36
36
## Choose between Route Directions and Matrix Routing
37
37
38
-
The Route Directions APIs return instructions including the travel time and the coordinates for a route path. The Route Matrix API lets you calculate the travel time and distances for a set of routes that are defined by origin and destination locations. For every given origin, the Matrix API calculates the cost (travel time and distance) of routing from that origin to every given destination. These API allow you to specify parameters such as the desired departure time, arrival times, and the vehicle type, like car or truck. They all use real-time or predictive traffic data accordingly to return the most optimal routes.
38
+
The Route Directions APIs return instructions including the travel time and the coordinates for a route path. The Route Matrix API lets you calculate the travel time and distances for a set of routes defined by origin and destination locations. For every given origin, the Matrix API calculates the cost (travel time and distance) of routing from that origin to every given destination. These API allow you to specify parameters such as the desired departure time, arrival times, and the vehicle type, like car or truck. They all use real-time or predictive traffic data accordingly to return the most optimal routes.
39
39
40
40
Consider calling Route Directions APIs if your scenario is to:
41
41
@@ -50,7 +50,7 @@ Consider calling Matrix Routing API if your scenario is to:
50
50
* Sort potential routes by their actual travel distance or time. The Matrix API returns only travel times and distances for each origin and destination combination.
51
51
* Cluster data based on travel time or distances. For example, your company has 50 employees, find all employees that live within 20 minute Drive Time from your office.
52
52
53
-
Here is a comparison to show some capabilities of the Route Directions and Matrix APIs:
53
+
Here's a comparison to show some capabilities of the Route Directions and Matrix APIs:
54
54
55
55
| Azure Maps API | Max number of queries in the request | Avoid areas | Truck and electric vehicle routing | Waypoints and Traveling Salesman optimization | Supporting points |
@@ -63,11 +63,11 @@ To learn more about electric vehicle routing capabilities, see our tutorial on h
63
63
64
64
## Request historic and real-time data
65
65
66
-
By default, the Route service assumes the traveling mode is a car and the departure time is now. It returns route based on real-time traffic conditions unless a route calculation request specifies otherwise. Fixed time-dependent traffic restrictions, like 'Left turns aren't allowed between 4:00 PM to 6:00 PM' are captured and will be considered by the routing engine. Road closures, like roadworks, will be considered unless you specifically request a route that ignores the current live traffic. To ignore the current traffic, set `traffic` to `false` in your API request.
66
+
By default, the Route service assumes the traveling mode is a car and the departure time is now. It returns route based on real-time traffic conditions unless a route calculation request specifies otherwise. The routing engine factors fixed time-dependent traffic restrictions, like 'Left turns aren't allowed between 4:00 PM to 6:00 PM'. Road closures, like roadworks, are considered unless you specifically request a route that ignores the current live traffic. To ignore the current traffic, set `traffic` to `false` in your API request.
67
67
68
-
The route calculation **travelTimeInSeconds** value includes the delay due to traffic. It's generated by leveraging the current and historic travel time data, when departure time is set to now. If your departure time is set in the future, the APIs return predicted travel times based on historical data.
68
+
The route calculation **travelTimeInSeconds** value includes the delay due to traffic. It's generated by using the current and historic travel time data, when departure time is set to now. If your departure time is set in the future, the APIs return predicted travel times based on historical data.
69
69
70
-
If you include the **computeTravelTimeFor=all** parameter in your request, then the summary element in the response will have the following additional fields including historical traffic conditions:
70
+
If you include the **computeTravelTimeFor=all** parameter in your request, then the summary element in the response has the following fields including historical traffic conditions:
71
71
72
72
| Element | Description|
73
73
| :--- | :--- |
@@ -85,7 +85,7 @@ In the first example below the departure time is set to the future, at the time
The response contains a summary element, like the one below. Because the departure time is set to the future, the **trafficDelayInSeconds** value is zero. The **travelTimeInSeconds** value is calculated using time-dependent historic traffic data. So, in this case, the **travelTimeInSeconds** value is equal to the **historicTrafficTravelTimeInSeconds** value.
88
+
The response contains a summary element, like the following example. Because the departure time is set to the future, the **trafficDelayInSeconds** value is zero. The **travelTimeInSeconds** value is calculated using time-dependent historic traffic data. So, in this case, the **travelTimeInSeconds** value is equal to the **historicTrafficTravelTimeInSeconds** value.
89
89
90
90
```json
91
91
"summary": {
@@ -102,13 +102,13 @@ The response contains a summary element, like the one below. Because the departu
102
102
103
103
### Sample query
104
104
105
-
In the second example below, we have a real-time routing request, where departure time is now. It's not explicitly specified in the URL because it's the default value.
105
+
In the next example, we have a real-time routing request, where departure time is now. It's not explicitly specified in the URL because it's the default value.
The response contains a summary as shown below. Because of congestions, the **trafficDelaysInSeconds** value is greater than zero. It's also greater than **historicTrafficTravelTimeInSeconds**.
111
+
The response contains a summary as shown in the following example. Because of congestion, the **trafficDelaysInSeconds** value is greater than zero. It's also greater than **historicTrafficTravelTimeInSeconds**.
112
112
113
113
```json
114
114
"summary": {
@@ -125,7 +125,7 @@ The response contains a summary as shown below. Because of congestions, the **tr
125
125
126
126
## Request route and leg details
127
127
128
-
By default, the Route service will return an array of coordinates. The response will contain the coordinates that make up the path in a list named `points`. Route response also includes the distance from the start of the route and the estimated elapsed time. These values can be used to calculate the average speed for the entire route.
128
+
By default, the Route service returns an array of coordinates. The response contains the coordinates that make up the path in a list named `points`. Route response also includes the distance from the start of the route and the estimated elapsed time. These values can be used to calculate the average speed for the entire route.
129
129
130
130
The following image shows the `points` element.
131
131
@@ -165,13 +165,13 @@ The Route API returns directions that accommodate the dimensions of the truck an
165
165
166
166
### Sample query
167
167
168
-
Changing the US Hazmat Class, from the above query, will result in a different route to accommodate this change.
168
+
Changing the US Hazmat Class, from the above query, results in a different route to accommodate this change.
The response below is for a truck carrying a class 9 hazardous material, which is less dangerous than a class 1 hazardous material. When you expand the `guidance` element to read the directions, you'll notice that the directions aren't the same. There are more route instructions for the truck carrying class 1 hazardous material.
174
+
The following response is for a truck carrying a class 9 hazardous material, which is less dangerous than a class 1 hazardous material. When you expand the `guidance` element to read the directions, notice that the directions aren't the same. There are more route instructions for the truck carrying class 1 hazardous material.
175
175
176
176
177
177
@@ -191,7 +191,7 @@ The response contains the sections that are suitable for traffic along the given
This option can be used to color the sections when rendering the map, as in the image below:
194
+
This option can be used to color the sections when rendering the map, as in The following image:
195
195
196
196
197
197
@@ -203,7 +203,7 @@ Azure Maps currently provides two forms of route optimizations:
203
203
204
204
* Traveling salesman optimization, which changes the order of the waypoints to obtain the best order to visit each stop
205
205
206
-
For multi-stop routing, up to 150 waypoints may be specified in a single route request. The starting and ending coordinate locations can be the same, as would be the case with a round trip. But you need to provide at least one additional waypoint to make the route calculation. Waypoints can be added to the query in-between the origin and destination coordinates.
206
+
For multi-stop routing, up to 150 waypoints may be specified in a single route request. The starting and ending coordinate locations can be the same, as would be the case with a round trip. But you need to provide at least one more waypoint to make the route calculation. Waypoints can be added to the query in-between the origin and destination coordinates.
207
207
208
208
If you want to optimize the best order to visit the given waypoints, then you need to specify **computeBestOrder=true**. This scenario is also known as the traveling salesman optimization problem.
209
209
@@ -219,7 +219,7 @@ The response describes the path length to be 140,851 meters, and that it would t
The image below illustrates the path resulting from this query. This path is one possible route. It's not the optimal path based on time or distance.
222
+
The following image illustrates the path resulting from this query. This path is one possible route. It's not the optimal path based on time or distance.
@@ -255,9 +255,9 @@ You might have situations where you want to reconstruct a route to calculate zer
255
255
3. Order the locations based on the distance from the start of the route
256
256
4. Add these locations as supporting points in a new route request to [Post Route Directions]. To learn more about the supporting points, see the [Post Route Directions API documentation].
257
257
258
-
When calling [Post Route Directions], you can set the minimum deviation time or the distance constraints, along with the supporting points. Use these parameters if you want to offer alternative routes, but you also want to limit the travel time. When these constraints are used, the alternative routes will follow the reference route from the origin point for the given time or distance. In other words, the other routes diverge from the reference route per the given constraints.
258
+
When calling [Post Route Directions], you can set the minimum deviation time or the distance constraints, along with the supporting points. Use these parameters if you want to offer alternative routes, but you also want to limit the travel time. When these constraints are used, the alternative routes follow the reference route from the origin point for the given time or distance. In other words, the other routes diverge from the reference route per the given constraints.
259
259
260
-
The image below is an example of rendering alternative routes with specified deviation limits for the time and the distance.
260
+
The following image is an example of rendering alternative routes with specified deviation limits for the time and the distance.
0 commit comments