Route - Post Directions
Use to get the best route between an origin and destination for automobile, commercial trucks and walking routes.
The Route Directions
API is an HTTP POST
request that returns the ideal route between an origin and destination for automobile (driving), commercial trucks and walking routes. The route passes through a series of waypoints if specified. A waypoint is a geographical location defined by longitude and latitude that is used for navigational purposes. The route considers factors such as current traffic and the typical road speeds on the requested day of the week and time of day.
The API returns the distance, estimated travel time, and a representation of the route geometry. More routing information such as an optimized waypoint order or turn by turn instructions is also available, depending on the parameters used.
The Route Directions considers local laws, vehicle dimensions, cargo type, max speed, bridge and tunnel heights to calculate the truck specific routes and avoid complex maneuvers and difficult roads. Not all trucks can travel the same routes as other vehicles due to certain restrictions based on the vehicle profile or cargo type. For example, highways often have separate speed limits for trucks, some roads don't allow trucks with flammable or hazardous materials, and there can be height and weight restriction on bridges.
Up to 25 waypoints and 10 viaWaypoints between any two waypoints is supported for driving and walking routes. Each set of waypoints creates a separate route Leg. ViaWaypoints define the route path and can be used for route creation through specific locations, but they don't create route Legs. Truck routes support up to 150 waypoints but don't support viaWaypoints.
For information about routing availability in countries/regions, see Azure Maps routing coverage.
Important
By using this feature, you agree to the preview legal terms. For more information, see Preview Supplemental Terms.
POST https://atlas.microsoft.com/route/directions?api-version=2023-10-01-preview
Name | In | Required | Type | Description |
---|---|---|---|---|
api-version
|
query | True |
string |
Version number of Azure Maps API. |
Media Types: "application/geo+json"
Name | Required | Type | Description |
---|---|---|---|
x-ms-client-id |
string |
Specifies which account is intended for usage in conjunction with the Microsoft Entra ID security model. It represents a unique ID for the Azure Maps account and can be retrieved from the Azure Maps management plane Account API. To use Microsoft Entra ID security in Azure Maps see the following articles for guidance. |
|
Accept-Language |
string |
Language in which routing results should be returned. For more information, see Localization support in Azure Maps. |
Media Types: "application/geo+json"
Name | Required | Type | Description |
---|---|---|---|
features | True |
Driving and walking routes are defined by a set of waypoints(stops) and viaWaypoints (intermediate locations that the route must pass through). You can have a maximum of 25 waypoints, and a maximum of 10 viaWaypoints between each set of waypoints. Truck route supports up to 150 waypoints and viaWaypoints are not supported. A route must have a minimum of 2 waypoints and the start and end points of the route cannot be viaWaypoints. Both waypoint and viaWaypoint locations must be specified as a valid GeoJSON Point feature object along with pointIndex that specifies the order of the locations. For more information on the GeoJSON format, see RFC 7946. |
|
type | True |
Specifies the |
|
arriveAt |
string |
The date and time of arrival at the destination point formatted as a The Example: "arriveAt": "2023-06-01T09:30:00.000-07:00" |
|
avoid |
Avoid[] |
Specifies restrictions that the route calculation should honor when determining the route. Avoid supports multiple values in a request and is only supported for the driving and truck travelMode. Example: "avoid": ["limitedAccessHighways", "tolls"] |
|
departAt |
string |
The date and time of departure from the origin point formatted as a The Examples: "departAt": "2023-06-01T09:30:00.000-07:00" |
|
heading |
integer |
The initial directional heading of the vehicle in degrees starting at true North and continuing in clockwise direction. North is 0 degrees, east is 90 degrees, south is 180 degrees, west is 270 degrees. Possible values 0-359 |
|
maxRouteCount |
integer |
The maximum number of routes to return. Available for the driving and truck travel modes. For driving routes, this parameter supports routes with up to two waypoints in addition to the origin and destination and avoid parameter must not be set. Default: "maxRouteCount":1 Minimum: "maxRouteCount":1 Maximum: "maxRouteCount":3 |
|
optimizeRoute |
Specifies the parameter to use to optimize the route. If not defined, the default is "fastestWithoutTraffic" which returns the route to minimize the travel time without using current traffic information. Example: "optimizeRoute":"shortest" |
||
optimizeWaypointOrder |
boolean |
Re-order the route waypoints using a fast heuristic algorithm to reduce the route cost specified with the optimize parameter. The origin and destination are excluded from the optimized waypoint and their position is considered fixed. Acceptable values are true or false.
|
|
routeOutputOptions |
Include the desired route information from the response. By default, the itinerary is included in the response. Supports multiple values such as "routeOutputOptions": ["routePath", "regionTravelSummary"] |
||
travelMode |
The mode of travel for the requested route. If not defined, the default value is "driving" that returns the route optimized for cars.
Example: "travelMode":"driving" |
||
vehicleSpec |
Specifies the vehicle attributes such as size, weight, max speed, type of cargo for truck routing only. This helps avoid low bridge clearances, road restrictions, difficult right turns to provide the optimized truck route based on the vehicle specifications.
|
Name | Type | Description |
---|---|---|
200 OK |
OK Media Types: "application/geo+json", "application/json" |
|
Other Status Codes |
An unexpected error occurred. Media Types: "application/geo+json", "application/json" Headers x-ms-error-code: string |
These are the Microsoft Entra OAuth 2.0 Flows. When paired with Azure role-based access control it can be used to control access to Azure Maps REST APIs. Azure role-based access controls are used to designate access to one or more Azure Maps resource account or sub-resources. Any user, group, or service principal can be granted access via a built-in role or a custom role composed of one or more permissions to Azure Maps REST APIs.
To implement scenarios, we recommend viewing authentication concepts. In summary, this security definition provides a solution for modeling application(s) via objects capable of access control on specific APIs and scopes.
Note
- This security definition requires the use of the
x-ms-client-id
header to indicate which Azure Maps resource the application is requesting access to. This can be acquired from the Maps management API. - The
Authorization URL
is specific to the Azure public cloud instance. Sovereign clouds have unique Authorization URLs and Microsoft Entra ID configurations. - The Azure role-based access control is configured from the Azure management plane via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.
- Usage of the Azure Maps Web SDK allows for configuration based setup of an application for multiple use cases.
- For more information on Microsoft identity platform, see Microsoft identity platform overview.
Type:
oauth2
Flow:
implicit
Authorization URL:
https://login.microsoftonline.com/common/oauth2/authorize
Name | Description |
---|---|
https://atlas.microsoft.com/.default | https://atlas.microsoft.com/.default |
This is a shared key that is provisioned when creating an Azure Maps resource through the Azure management plane via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.
With this key, any application is authorized to access all REST APIs. In other words, these can currently be treated as master keys to the account which they are issued for.
For publicly exposed applications, our recommendation is to use server-to-server access of Azure Maps REST APIs where this key can be securely stored.
Type:
apiKey
In:
header
This is a shared access signature token is created from the List SAS operation on the Azure Maps resource through the Azure management plane via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.
With this token, any application is authorized to access with Azure role-based access controls and fine-grain control to the expiration, rate, and region(s) of use for the particular token. In other words, the SAS Token can be used to allow applications to control access in a more secured way than the shared key.
For publicly exposed applications, our recommendation is to configure a specific list of allowed origins on the Map account resource to limit rendering abuse and regularly renew the SAS Token.
Type:
apiKey
In:
header
Successfully retrieve a route between an origin and a destination with additional parameters in the body
Sample request
POST https://atlas.microsoft.com/route/directions?api-version=2023-10-01-preview
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"coordinates": [
-122.201399,
47.608678
],
"type": "Point"
},
"properties": {
"pointIndex": 0,
"pointType": "waypoint"
}
},
{
"type": "Feature",
"geometry": {
"coordinates": [
-122.20687,
47.612002
],
"type": "Point"
},
"properties": {
"pointIndex": 1,
"pointType": "viaWaypoint"
}
},
{
"type": "Feature",
"geometry": {
"coordinates": [
-122.201669,
47.615076
],
"type": "Point"
},
"properties": {
"pointIndex": 2,
"pointType": "waypoint"
}
}
],
"optimizeRoute": "fastestWithTraffic",
"routeOutputOptions": [
"routePath"
],
"maxRouteCount": 3,
"travelMode": "driving"
}
Sample response
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-122.20147,
47.608676
]
},
"properties": {
"type": "Waypoint",
"routePathPoint": {
"legIndex": 0,
"pointIndex": 0
},
"order": {
"inputIndex": 0
},
"compassDirection": "north",
"instruction": {
"formattedText": "<Action>Head</Action> <CmpsDir>north</CmpsDir> on <RoadName>Bellevue Way SE</RoadName> toward <Toward>SE 1st St</Toward>",
"maneuverType": "DepartStart",
"text": "Head north on Bellevue Way SE toward SE 1st St"
},
"sideOfStreet": "Unknown",
"towardsRoadName": "SE 1st St",
"distanceInMeters": 98.2,
"durationInSeconds": 19,
"steps": [
{
"routePathRange": {
"legIndex": 0,
"range": [
0,
1
]
},
"maneuverType": "DepartStart",
"compassDegrees": 358,
"roadType": "Arterial",
"names": [
"Bellevue Way SE"
]
}
],
"travelMode": "driving"
}
},
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-122.201495,
47.610109
]
},
"properties": {
"type": "ManeuverPoint",
"routePathPoint": {
"legIndex": 0,
"pointIndex": 1
},
"compassDirection": "north",
"instruction": {
"formattedText": "<Action>Turn</Action> <TurnDir>left</TurnDir> onto <RoadName>Main st</RoadName>",
"maneuverType": "TurnLeft",
"text": "Turn left onto Main st"
},
"sideOfStreet": "Unknown",
"distanceInMeters": 253.5,
"durationInSeconds": 81,
"steps": [
{
"routePathRange": {
"legIndex": 0,
"range": [
1,
3
]
},
"maneuverType": "TurnLeft",
"compassDegrees": 358,
"roadType": "Arterial",
"names": [
"Main st"
]
}
],
"travelMode": "driving"
}
},
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-122.206817,
47.610185
]
},
"properties": {
"type": "ManeuverPoint",
"routePathPoint": {
"legIndex": 0,
"pointIndex": 3
},
"compassDirection": "north",
"instruction": {
"formattedText": "<Action>Turn</Action> <TurnDir>right</TurnDir> onto <RoadName>100th Ave NE</RoadName>",
"maneuverType": "TurnRight",
"text": "Turn right onto 100th Ave NE"
},
"sideOfStreet": "Unknown",
"distanceInMeters": 252.9,
"durationInSeconds": 49,
"steps": [
{
"routePathRange": {
"legIndex": 0,
"range": [
3,
5
]
},
"maneuverType": "TurnRight",
"compassDegrees": 357,
"roadType": "Arterial",
"names": [
"100th Ave NE"
]
}
],
"travelMode": "driving"
}
},
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-122.206971,
47.61384
]
},
"properties": {
"type": "ManeuverPoint",
"routePathPoint": {
"legIndex": 0,
"pointIndex": 6
},
"compassDirection": "east",
"instruction": {
"formattedText": "<Action>Turn</Action> <TurnDir>right</TurnDir> onto <RoadName>NE 4th St</RoadName>",
"maneuverType": "TurnRight",
"text": "Turn right onto NE 4th St"
},
"sideOfStreet": "Unknown",
"distanceInMeters": 247.9,
"durationInSeconds": 77,
"steps": [
{
"routePathRange": {
"legIndex": 0,
"range": [
6,
9
]
},
"maneuverType": "TurnRight",
"compassDegrees": 90,
"roadType": "Arterial",
"names": [
"NE 4th St"
]
}
],
"travelMode": "driving"
}
},
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-122.201664,
47.61386
]
},
"properties": {
"type": "ManeuverPoint",
"routePathPoint": {
"legIndex": 0,
"pointIndex": 9
},
"compassDirection": "east",
"instruction": {
"formattedText": "<Action>Turn</Action> <TurnDir>left</TurnDir> onto <RoadName>Bellevue Way NE</RoadName>",
"maneuverType": "TurnLeft",
"text": "Turn left onto Bellevue Way NE"
},
"sideOfStreet": "Unknown",
"distanceInMeters": 94.4,
"durationInSeconds": 38,
"steps": [
{
"routePathRange": {
"legIndex": 0,
"range": [
9,
11
]
},
"maneuverType": "TurnLeft",
"compassDegrees": 91,
"roadType": "Arterial",
"names": [
"Bellevue Way NE"
]
}
],
"travelMode": "driving"
}
},
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-122.201603,
47.615137
]
},
"properties": {
"type": "Waypoint",
"routePathPoint": {
"legIndex": 0,
"pointIndex": 11
},
"order": {
"inputIndex": 2
},
"compassDirection": "north",
"instruction": {
"formattedText": "<Action>Arrive</Action> at <WaypointName>Bellevue Way NE</WaypointName>",
"maneuverType": "ArriveFinish",
"text": "Arrive at Bellevue Way NE",
"hints": [
{
"hintType": "PreviousIntersection",
"text": "The last intersection before your destination is NE 4th St"
}
]
},
"sideOfStreet": "Unknown",
"distanceInMeters": 0,
"durationInSeconds": 0,
"steps": [
{
"routePathRange": {
"legIndex": 0,
"range": [
11,
11
]
},
"maneuverType": "ArriveFinish",
"compassDegrees": 357,
"roadType": "Arterial",
"names": [
"Bellevue Way NE"
]
}
],
"travelMode": "driving"
}
},
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-122.206894,
47.612001
]
},
"properties": {
"type": "ViaWaypoint",
"names": [
"100th Ave NE"
],
"routePathPoint": {
"pointIndex": 5,
"legIndex": 0
},
"order": {
"inputIndex": 1
}
}
},
{
"type": "Feature",
"geometry": {
"type": "MultiLineString",
"coordinates": [
[
[
-122.20147,
47.608675
],
[
-122.201494,
47.610108
],
[
-122.201496,
47.610196
],
[
-122.206817,
47.610185
],
[
-122.206824,
47.610369
],
[
-122.206893,
47.612001
],
[
-122.20697,
47.613839
],
[
-122.206832,
47.613839
],
[
-122.204428,
47.61379
],
[
-122.201664,
47.61386
],
[
-122.201547,
47.613857
],
[
-122.201603,
47.615137
]
]
]
},
"bbox": [
47.608676,
-122.206971,
47.615137,
-122.20147
],
"properties": {
"type": "RoutePath",
"resourceId": "v70,h-1241513931,i0,a0,cen-US,dAMA8xD0s2wg1,y1,s3,m1,o1,t4,wuOUjKenNR0CdnKG444xewA2~AISjUSdxkDoBAADgAdG_yz4A0~QmVsbGV2dWUgV2F5IFNF0~~~~~~~~v12,wFYvfFFbOR0CBIatbPY1ewA2~AISjUScpizoBAADgARBojT4A0~MTAwdGggQXZlIE5F0~~~1~~~~~v12,w-kZ0z7rOR0B95xcl6IxewA2~AISjUSchJDoBAADgAQAAgD8A0~QmVsbGV2dWUgV2F5IE5F0~~~~~~~~v12,k0,qatt:1",
"distanceInMeters": 947,
"durationInSeconds": 266,
"durationTrafficInSeconds": 295,
"trafficDataUsed": "None",
"trafficCongestion": "Mild",
"departureTime": "2023-08-28T18:00:00+00:00",
"arrivalTime": "2023-08-28T18:04:55+00:00",
"legs": [
{
"description": "100th Ave NE, NE 4th St",
"routePathRange": {
"range": [
0,
11
],
"legIndex": 0
},
"subLegs": [
{
"routePathRange": {
"range": [
0,
5
],
"legIndex": 0
},
"distanceInMeters": 477.8,
"durationInSeconds": 128,
"durationTrafficInSeconds": 138
},
{
"routePathRange": {
"range": [
5,
11
],
"legIndex": 0
},
"distanceInMeters": 469.1,
"durationInSeconds": 137,
"durationTrafficInSeconds": 157
}
],
"distanceInMeters": 947,
"durationInSeconds": 266,
"durationTrafficInSeconds": 295,
"departureTime": "2023-08-28T18:00:00+00:00",
"arrivalTime": "2023-08-28T18:04:55+00:00"
}
]
}
}
]
}
Name | Description |
---|---|
Admin |
The subdivision name in the country or region for an address. This element is typically treated as the first order administrative subdivision, but in some cases it also contains the second, third, or fourth order subdivision in a country, dependency, or region. |
Avoid |
Specifies restrictions that the route calculation should honor when determining the route. Avoid supports multiple values in a request and is only supported for the driving and truck travelMode. Example: "avoid": ["limitedAccessHighways", "tolls"] |
Directions |
This object is the request body. |
Feature |
|
Features |
GeoJSON feature object that contains Geometry object and additional properties of the route. |
Features |
Specifies the |
Feature |
Specifies the |
Geo |
A valid |
Hint |
Additional information that may be helpful in following a route. In addition to the hint text, this element has an attribute hintType that specifies what the hint refers to, such as “NextIntersection.” Hint is an optional element. |
Input |
Specifies the input waypoint and viaWaypoint |
Input |
Waypoint type on the route. It can be a stop or an intermediate location that the route must pass through. |
Instruction |
A description of a maneuver in a set of directions. |
Leg |
Information about a section of a route between two waypoints. More information about the fields contained in a route Leg: |
Maneuver |
Specifies the driving instructions and additional properties for each maneuver point in the route Leg. |
Maneuver |
The type of maneuver described by this detail collection. The ManeuverType in A detail collection can provide information for a portion of the maneuver described by the maneuverType attribute of the corresponding Instruction. For example the maneuverType attribute of an Instruction may specify TurnLeftThenTurnRight as the maneuver while the associated detail items may specify specifics about the TurnLeft and TurnRight maneuvers. |
Maps |
The error detail. |
Maps |
Common error response for Azure Maps APIs to return error details for failed operations. |
Maps |
An object containing more specific information than the current object about the error. |
Multi |
Specifies the |
Optimize |
Specifies the parameter to use to optimize the route. If not defined, the default is "fastestWithoutTraffic" which returns the route to minimize the travel time without using current traffic information. Example: "optimizeRoute":"shortest" |
Order |
Sequence for visiting waypoints and viaWaypoints. |
Point |
Specifies the |
Region |
Travel summary of distance, time, and toll road distance by two entity types: country (e.g. US, Canada) and administrative division or subregion (e.g. “state” in US and “province” in Canada). |
Road |
The type of road. |
Route |
This object is returned from a successful call. |
Route |
Include the desired route information from the response. By default, the itinerary is included in the response. Supports multiple values such as "routeOutputOptions": ["routePath", "regionTravelSummary"] |
Route |
Refers to the index of a point within a specific Leg of a route. |
Route |
Specifies the properties that describe the route's path in the response. |
Route |
Refers to the range covered by a specific Leg of a route or path. |
Route |
The mode of travel for the route path in the response. |
Side |
The side of the street where the destination is found based on the arrival direction. This field applies to the last maneuverPoint only. |
Step |
A route Leg contain turn-by-turn instructions. A step refers to a range of a route between two consecutive maneuverPoint. |
Sub |
Information about a segments of the route Leg defined by the route Leg waypoints and any intermediate via-waypoints. For example, if the route Leg has two via-waypoints in addition to start and end waypoints, there would be three (3) route sub-legs. |
Traffic |
The level of traffic congestion along the route. |
Traffic |
The type of real-time traffic data used to generate the route. |
Travel |
The mode of travel for the requested route. If not defined, the default value is "driving" that returns the route optimized for cars.
Example: "travelMode":"driving" |
Vehicle |
Types of cargo that may be classified as hazardous materials and restricted from some roads. Available vehicleLoadType values are US Hazmat classes 1 through 9, plus generic classifications for use in other countries. Values beginning with USHazmat are for US routing while otherHazmat should be used for all other countries. vehicleLoadType supports multiple values in a request. |
Vehicle |
Vehicle attributes are specified inside of a vehicleSpec. Different regions may have different definitions for the truck classification and types, e.g., light truck, medium truck, heavy truck, etc. To get the most accurate results of the route restrictions based on the truck specs, specify the vehicle attributes.
|
Via |
Specifies the properties of a |
Waypoint |
Specifies the properties of a Waypoint which is a specific location or point along a route or trip that serves as a reference or stopping point. |
The subdivision name in the country or region for an address. This element is typically treated as the first order administrative subdivision, but in some cases it also contains the second, third, or fourth order subdivision in a country, dependency, or region.
Name | Type | Description |
---|---|---|
distanceInMeters |
number |
The total distance traveled in meters within the administrative district. |
durationInSeconds |
integer |
Estimated travel time in seconds that does not include delays on the route due to traffic conditions. |
durationTrafficInSeconds |
integer |
The time that it takes, in seconds, to travel a corresponding |
longName |
string |
The long name of an address, such as Washington. |
Specifies restrictions that the route calculation should honor when determining the route. Avoid supports multiple values in a request and is only supported for the driving and truck travelMode.
Example: "avoid": ["limitedAccessHighways", "tolls"]
Name | Type | Description |
---|---|---|
borderCrossings |
string |
Avoids crossing country borders in the route. |
ferries |
string |
Avoids the use of ferries in the route. |
limitedAccessHighways |
string |
Avoids the use of limited access highways in the route. |
lowEmissionZones |
string |
Avoids low-emission zones in the route. |
tollRoads |
string |
Avoids the use of toll roads in the route. |
tunnels |
string |
Avoids the use of tunnels in the route. |
unpavedRoads |
string |
Avoids unpaved roads in the route. |
This object is the request body.
Name | Type | Default value | Description |
---|---|---|---|
arriveAt |
string |
The date and time of arrival at the destination point formatted as a The Example: "arriveAt": "2023-06-01T09:30:00.000-07:00" |
|
avoid |
Avoid[] |
Specifies restrictions that the route calculation should honor when determining the route. Avoid supports multiple values in a request and is only supported for the driving and truck travelMode. Example: "avoid": ["limitedAccessHighways", "tolls"] |
|
departAt |
string |
The date and time of departure from the origin point formatted as a The Examples: "departAt": "2023-06-01T09:30:00.000-07:00" |
|
features |
Driving and walking routes are defined by a set of waypoints(stops) and viaWaypoints (intermediate locations that the route must pass through). You can have a maximum of 25 waypoints, and a maximum of 10 viaWaypoints between each set of waypoints. Truck route supports up to 150 waypoints and viaWaypoints are not supported. A route must have a minimum of 2 waypoints and the start and end points of the route cannot be viaWaypoints. Both waypoint and viaWaypoint locations must be specified as a valid GeoJSON Point feature object along with pointIndex that specifies the order of the locations. For more information on the GeoJSON format, see RFC 7946. |
||
heading |
integer |
The initial directional heading of the vehicle in degrees starting at true North and continuing in clockwise direction. North is 0 degrees, east is 90 degrees, south is 180 degrees, west is 270 degrees. Possible values 0-359 |
|
maxRouteCount |
integer |
The maximum number of routes to return. Available for the driving and truck travel modes. For driving routes, this parameter supports routes with up to two waypoints in addition to the origin and destination and avoid parameter must not be set. Default: "maxRouteCount":1 Minimum: "maxRouteCount":1 Maximum: "maxRouteCount":3 |
|
optimizeRoute | fastestWithoutTraffic |
Specifies the parameter to use to optimize the route. If not defined, the default is "fastestWithoutTraffic" which returns the route to minimize the travel time without using current traffic information. Example: "optimizeRoute":"shortest" |
|
optimizeWaypointOrder |
boolean |
False |
Re-order the route waypoints using a fast heuristic algorithm to reduce the route cost specified with the optimize parameter. The origin and destination are excluded from the optimized waypoint and their position is considered fixed. Acceptable values are true or false.
|
routeOutputOptions | [ "itinerary" ] |
Include the desired route information from the response. By default, the itinerary is included in the response. Supports multiple values such as "routeOutputOptions": ["routePath", "regionTravelSummary"] |
|
travelMode | driving |
The mode of travel for the requested route. If not defined, the default value is "driving" that returns the route optimized for cars.
Example: "travelMode":"driving" |
|
type |
Specifies the |
||
vehicleSpec |
Specifies the vehicle attributes such as size, weight, max speed, type of cargo for truck routing only. This helps avoid low bridge clearances, road restrictions, difficult right turns to provide the optimized truck route based on the vehicle specifications.
|
GeoJSON
FeatureCollection
object that contains a list of Features. For more information, see RFC 7946, section 3.3.
Name | Type | Description |
---|---|---|
features |
|
|
nextLink |
string |
The is the link to the next page of the features returned. If it's the last page, the field will not exist. |
type |
Specifies the |
GeoJSON feature object that contains Geometry object and additional properties of the route.
Name | Type | Description |
---|---|---|
bbox |
number[] |
A rectangular area on the earth defined as a bounding box object. The sides of the rectangles are defined by latitude and longitude values. For more information, see RFC 7946, Section 5. Example: "bbox": [-10.0, -10.0, 10.0, 10.0] |
geometry | Geometry: |
A valid |
properties | FeatureProperties: |
Specifies the feature properties of the route like itinerary, route Legs and geometry, travel summary. |
type |
Specifies the |
Specifies the GeoJSON
type. The only supported object type is Feature. For more information, see RFC 7946.
Name | Type | Description |
---|---|---|
Feature |
string |
Specifies the |
Specifies the GeoJSON
type. The only supported object type is FeatureCollection
. For more information, see RFC 7946.
Name | Type | Description |
---|---|---|
FeatureCollection |
string |
Specifies the |
A valid GeoJSON Point
geometry type. Please refer to RFC 7946 for details.
Name | Type | Description |
---|---|---|
coordinates |
number[] |
A |
type |
string:
Point |
Specifies the |
Additional information that may be helpful in following a route. In addition to the hint text, this element has an attribute hintType that specifies what the hint refers to, such as “NextIntersection.” Hint is an optional element. Note
: Only supported for driving travelMode.
Name | Type | Description |
---|---|---|
hintType |
string |
hint type. |
text |
string |
hint text. |
Specifies the input waypoint and viaWaypoint GeoJSON
feature object and additional properties. For more information, see RFC 7946.
Name | Type | Default value | Description |
---|---|---|---|
geometry | GeoJsonPoint: |
A valid |
|
properties.pointIndex |
integer |
Identify and order the sequence of waypoints in the route. The default value is the |
|
properties.pointType | waypoint |
Waypoint type on the route. It can be a stop or an intermediate location that the route must pass through. |
|
type |
Specifies the |
Waypoint type on the route. It can be a stop or an intermediate location that the route must pass through.
Name | Type | Description |
---|---|---|
viaWaypoint |
string |
A viaWaypoint is a specific waypoint that must be passed through or visited along a route or trip. |
waypoint |
string |
A waypoint is a specific location or point along a route or trip that serves as a reference or stopping point. |
A description of a maneuver in a set of directions.
Name | Type | Description |
---|---|---|
formattedText |
string |
The formatted text description of the instruction. |
hints |
Hint[] |
Additional information that may be helpful in following a route. In addition to the hint text, this element has an attribute hintType that specifies what the hint refers to, such as “NextIntersection.” Hint is an optional element and a route step can contain more than one hint. |
maneuverType |
The type of maneuver described by this detail collection. The ManeuverType in A detail collection can provide information for a portion of the maneuver described by the maneuverType attribute of the corresponding Instruction. For example the maneuverType attribute of an Instruction may specify TurnLeftThenTurnRight as the maneuver while the associated detail items may specify specifics about the TurnLeft and TurnRight maneuvers. |
|
text |
string |
The plain text description of the instruction. |
Information about a section of a route between two waypoints. More information about the fields contained in a route Leg:
Name | Type | Description |
---|---|---|
arrivalTime |
|
The estimated arrival time for the leg, which takes into account the traffic conditions, is formatted as a dateTime value defined by RFC 3339, section 5.6. It will reference the timezone offset by either |
departureTime |
|
The estimated departure time for the leg, which takes into account the traffic conditions, is formatted as a dateTime value defined by RFC 3339, section 5.6. It will reference the timezone offset by either |
description |
string |
A short description of the route. |
distanceInMeters |
number |
The physical distance in meters covered by a route Leg. |
durationInSeconds |
integer |
Estimated travel time in seconds that does not include delays on the route due to traffic conditions. |
durationTrafficInSeconds |
integer |
The time that it takes, in seconds, to travel a corresponding |
regionTravelSummary |
Include travel summary of distance, time, and toll road distance by two entity types: country (e.g. US, Canada) and administrative division or subregion (e.g. “state” in US and “province” in Canada). |
|
routePathRange |
Refers to the range covered by a specific Leg of a route or path. |
|
subLegs |
Sub |
Information about a segments of the route Leg defined by the route Leg waypoints and any intermediate via-waypoints. For example, if the route Leg has two via-waypoints in addition to start and end waypoints, there would be three (3) route sub-legs. |
Specifies the driving instructions and additional properties for each maneuver point in the route Leg.
Name | Type | Default value | Description |
---|---|---|---|
compassDirection |
string |
The direction of travel associated with a maneuver on a route, such as south or southwest. |
|
distanceInMeters |
number |
The physical distance in meters covered by this route step. |
|
durationInSeconds |
integer |
The time that it takes, in seconds, to travel a corresponding |
|
exitIdentifier |
string |
The name or number of the exit associated with this route step. |
|
instruction |
A description of a maneuver in a set of directions. |
||
order |
Sequence for visiting waypoints and viaWaypoints. |
||
routePathPoint |
Refers to the index of a point within a specific Leg of a route. |
||
sideOfStreet |
The side of the street where the destination is found based on the arrival direction. This field applies to the last maneuverPoint only. |
||
signs |
string[] |
Signage text for the route. There may be more than one sign value. |
|
steps |
Step[] |
Steps between two consecutive maneuver points. |
|
towardsRoadName |
string |
The name of the street that the route goes towards in the first |
|
travelMode | driving |
The mode of travel for the route path in the response. |
|
type |
string:
Maneuver |
Output type. |
The type of maneuver described by this detail collection. The ManeuverType in A detail collection can provide information for a portion of the maneuver described by the maneuverType attribute of the corresponding Instruction. For example the maneuverType attribute of an Instruction may specify TurnLeftThenTurnRight as the maneuver while the associated detail items may specify specifics about the TurnLeft and TurnRight maneuvers.
Name | Type | Description |
---|---|---|
ArriveFinish |
string |
Arrive at the final destination. |
ArriveIntermediate |
string |
Arrive at an intermediate waypoint. |
BearLeft |
string |
Bear left. |
BearLeftThenBearLeft |
string |
Bear left and then bear left again. |
BearLeftThenBearRight |
string |
Bear left and then bear right. |
BearLeftThenTurnLeft |
string |
Bear left and then turn left. |
BearLeftThenTurnRight |
string |
Bear left and then turn right. |
BearRight |
string |
Bear right. |
BearRightThenBearLeft |
string |
Bear right and then bear left. |
BearRightThenBearRight |
string |
Bear right and then bear right again. |
BearRightThenTurnLeft |
string |
Bear right and then turn left. |
BearRightThenTurnRight |
string |
Bear right and then turn right. |
BearThenKeep |
string |
Bear instruction and then a keep instruction |
BearThenMerge |
string |
Bear instruction and then a merge instruction. |
Continue |
string |
Continue on the current road. |
DepartIntermediateStop |
string |
Leave an intermediate waypoint in a different direction and road than you arrived on. |
DepartIntermediateStopReturning |
string |
Leave an intermediate waypoint in the same direction and on the same road that you arrived on. |
DepartStart |
string |
Leave the starting point. |
EnterRoundabout |
string |
Enter a roundabout. |
EnterThenExitRoundabout |
string |
Enter and exit a roundabout. |
ExitRoundabout |
string |
Exit a roundabout. |
ExitRoundaboutLeft |
string |
At the roundabout take the exit on the left. |
ExitRoundaboutRight |
string |
At the roundabout take the exit on the right. |
Follow |
string |
Follow. |
GoAroundRoundabout |
string |
Go around the roundabout. |
KeepLeft |
string |
Keep left onto a different road. |
KeepOnRampLeft |
string |
Keep left and continue onto ramp. |
KeepOnRampRight |
string |
Keep right and continue onto ramp. |
KeepOnRampStraight |
string |
Keep straight and continue onto ramp. |
KeepRight |
string |
Keep right onto a different road. |
KeepStraight |
string |
Keep straight onto a different road. |
KeepToStayLeft |
string |
Keep left to stay on the same road. |
KeepToStayRight |
string |
Keep right to stay on the same road. |
KeepToStayStraight |
string |
Keep straight to stay on the same road. |
MergeFreeway |
string |
Merge onto a freeway. |
MergeHighway |
string |
Merge onto a highway. |
MergeMotorway |
string |
Merge onto a motorway. |
MotorwayExitLeft |
string |
Take the left exit. |
MotorwayExitRight |
string |
Take the right exit. |
None |
string |
No instruction. |
RampThenHighwayLeft |
string |
Take left ramp onto highway. This is part of a combined instruction. |
RampThenHighwayRight |
string |
Take right ramp onto highway. This is part of a combined instruction. |
RampThenHighwayStraight |
string |
Stay straight to take ramp onto highway. This is part of a combined instruction. |
RoadNameChange |
string |
Road name changes. |
SwitchToMainRoad |
string |
Switch to the main road. |
SwitchToParallelRoad |
string |
Switch to the parallel road. |
Take |
string |
Take the road. This instruction is used when you are entering or exiting a ferry. |
TakeExit |
string |
Take the exit. |
TakeFerry |
string |
Take the ferry. |
TakeRamp |
string |
Take ramp. |
TakeRampLeft |
string |
Take ramp to the left. |
TakeRampRight |
string |
Take ramp to the right. |
TakeRampStraight |
string |
Stay straight to take ramp. |
TurnBack |
string |
Turn back sharply. |
TurnLeft |
string |
Turn left. |
TurnLeftSharp |
string |
Take a sharp left turn. |
TurnLeftThenBearLeft |
string |
Turn left and then bear left. |
TurnLeftThenBearRight |
string |
Turn left and then bear right. |
TurnLeftThenTurnLeft |
string |
Turn left and then turn left again. |
TurnLeftThenTurnRight |
string |
Turn left and then turn right. |
TurnRight |
string |
Turn right. |
TurnRightSharp |
string |
Take a sharp right turn. |
TurnRightThenBearLeft |
string |
Turn right and then bear left. |
TurnRightThenBearRight |
string |
Turn right and then bear right. |
TurnRightThenTurnLeft |
string |
Turn right and then turn left. |
TurnRightThenTurnRight |
string |
Turn right and then turn right again |
TurnThenMerge |
string |
Turn instruction followed by a merge instruction. |
TurnToStayLeft |
string |
Turn left to stay on the same road. |
TurnToStayRight |
string |
Turn right to stay on the same road. |
UTurn |
string |
Make a u-turn to go in the opposite direction. |
Unknown |
string |
The instruction is unknown. |
Wait |
string |
Wait |
Walk |
string |
Walk |
The error detail.
Name | Type | Description |
---|---|---|
code |
string |
One of a server-defined set of error codes. |
details |
An array of details about specific errors that led to this reported error. |
|
innererror |
An object containing more specific information than the current object about the error. |
|
message |
string |
A human-readable representation of the error. |
target |
string |
The target of the error. |
Common error response for Azure Maps APIs to return error details for failed operations.
Name | Type | Description |
---|---|---|
error |
The error detail. |
An object containing more specific information than the current object about the error.
Name | Type | Description |
---|---|---|
code |
string |
The error code. |
innererror |
An object containing more specific information than the current object about the error. |
Specifies the GeoJSON
MultiLineString Geometry object. For more information, see RFC 7946.
Name | Type | Description |
---|---|---|
coordinates |
number[] |
Coordinates for the |
type |
string:
Multi |
Specifies the geometry type for the 'GeoJSON` Geometry object. For more information, see RFC 7946. |
Specifies the parameter to use to optimize the route. If not defined, the default is "fastestWithoutTraffic" which returns the route to minimize the travel time without using current traffic information.
Example: "optimizeRoute":"shortest"
Name | Type | Description |
---|---|---|
fastestAvoidClosureWithoutTraffic |
string |
The route is calculated to minimize the time and avoid road closures. No traffic information except for road closures is used in the calculation. |
fastestWithTraffic |
string |
The route is calculated to minimize the time using current traffic information. |
fastestWithoutTraffic |
string |
Finds the fastest route, without factoring in traffic information. |
shortest |
string |
The route is calculated to minimize the distance. Traffic information is not used. |
Sequence for visiting waypoints and viaWaypoints.
Name | Type | Description |
---|---|---|
inputIndex |
integer |
User-provided index for waypoint and viaWaypoint inputs. |
optimizedIndex |
integer |
System-optimized waypoint and viaWaypoint index. |
Specifies the GeoJSON
Point Geometry object. For more information, see RFC 7946.
Name | Type | Description |
---|---|---|
coordinates |
number[] |
A |
type |
string:
Point |
Specifies the geometry type for the 'GeoJSON` Geometry object. For more information, see RFC 7946. |
Travel summary of distance, time, and toll road distance by two entity types: country (e.g. US, Canada) and administrative division or subregion (e.g. “state” in US and “province” in Canada).
Name | Type | Description |
---|---|---|
adminDistricts |
adminDistrict array. |
|
countryRegion |
string |
Country region name. |
distanceInMeters |
number |
Length In Meters property |
durationInSeconds |
integer |
Estimated travel time in seconds that does not include delays on the route due to traffic conditions. |
durationTrafficInSeconds |
integer |
The time that it takes, in seconds, to travel a corresponding |
The type of road. Note
: Only supported for driving travelMode.
Name | Type | Description |
---|---|---|
Arterial |
string |
Arterial. |
Ferry |
string |
Ferry. |
Highway |
string |
Highway. |
LimitedAccessHighway |
string |
LimitedAccessHighway. |
MajorRoad |
string |
MajorRoad. |
NotApplicable |
string |
NotApplicable. |
Ramp |
string |
Ramp. |
Street |
string |
Street. |
WalkingPath |
string |
WalkingPath. |
This object is returned from a successful call.
Name | Type | Description |
---|---|---|
alternativeRoutes |
Alternative route. |
|
features |
|
|
nextLink |
string |
The is the link to the next page of the features returned. If it's the last page, the field will not exist. |
type |
Specifies the |
Include the desired route information from the response. By default, the itinerary is included in the response.
Supports multiple values such as "routeOutputOptions": ["routePath", "regionTravelSummary"]
Name | Type | Description |
---|---|---|
itinerary |
string |
Include detailed directions in the response. Detailed directions are provided as "ManeuverPoints" and contain details such as turn-by-turn instructions. |
regionTravelSummary |
string |
Include travel summary of distance, time, and toll road distance by two entity types: country (e.g., US, Canada) and administrative division or subregion (e.g., "state" in US and "province" in Canada). |
routePath |
string |
Include a GeoJSON MultiLineString RFC 7946, section 3.1.5 that describe the route's path in the response. |
routeSummary |
string |
Include only travel time and distance for the route, and do not provide other information. |
Refers to the index of a point within a specific Leg of a route.
Name | Type | Description |
---|---|---|
legIndex |
integer |
The route Leg index is a sequential number assigned to each Leg of the route to help identify and distinguish between different segments of the route. |
pointIndex |
integer |
Index of a point within a specific Leg. |
Specifies the properties that describe the route's path in the response.
Name | Type | Description |
---|---|---|
arrivalTime |
|
The estimated arrival time for the leg, which takes into account the traffic conditions, is formatted as a |
departureTime |
|
The estimated departure time for the leg, which takes into account the traffic conditions, is formatted as a |
distanceInMeters |
number |
The physical distance in meters covered by the entire route. |
durationInSeconds |
integer |
Estimated travel time in seconds that does not include delays on the route due to traffic conditions. |
durationTrafficInSeconds |
integer |
The time that it takes, in seconds, to travel a corresponding |
legs |
Leg[] |
An array of route Legs. Check route Leg object description for more information. |
resourceId |
string |
A unique ID for the resource. |
trafficCongestion |
The level of traffic congestion along the route. |
|
trafficDataUsed |
The type of real-time traffic data used to generate the route. |
|
type |
string:
Route |
Output type. |
Refers to the range covered by a specific Leg of a route or path.
Name | Type | Description |
---|---|---|
legIndex |
integer |
The route Leg index is a sequential number assigned to each Leg of the route to help identify and distinguish between different segments of the route. |
range |
integer[] |
Refers to the range covered by a specific Leg of a route or path. |
The mode of travel for the route path in the response.
Name | Type | Description |
---|---|---|
driving |
string |
Routes optimized for cars. |
other |
string |
RouteTravelMode is returned as "other" for the truck travelMode when the truck route is not available for a particular section of a route. |
truck |
string |
Routes optimized for large size trucks based on the vehicle specification. |
walking |
string |
Routes optimized for pedestrians. |
The side of the street where the destination is found based on the arrival direction. This field applies to the last maneuverPoint only.
Name | Type | Description |
---|---|---|
Left |
string |
Left. |
Right |
string |
Right. |
Unknown |
string |
Unknown. |
A route Leg contain turn-by-turn instructions. A step refers to a range of a route between two consecutive maneuverPoint.
Name | Type | Description |
---|---|---|
compassDegrees |
number |
The direction in degrees. |
maneuverType |
The type of maneuver described by this detail collection. The ManeuverType in A detail collection can provide information for a portion of the maneuver described by the maneuverType attribute of the corresponding Instruction. For example the maneuverType attribute of an Instruction may specify TurnLeftThenTurnRight as the maneuver while the associated detail items may specify specifics about the TurnLeft and TurnRight maneuvers. |
|
names |
string[] |
A street, highway or intersection where the maneuver occurs. If the maneuver is complex, there may be more than one name field in the details collection. The name field may also have no value. This can occur if the name is not known or if a street, highway or intersection does not have a name. |
roadType |
The type of road. |
|
routePathRange |
Refers to the range covered by a specific Leg of a route or path. |
Information about a segments of the route Leg defined by the route Leg waypoints and any intermediate via-waypoints. For example, if the route Leg has two via-waypoints in addition to start and end waypoints, there would be three (3) route sub-legs.
Name | Type | Description |
---|---|---|
distanceInMeters |
number |
The physical distance in meters covered by the sub-leg. |
durationInSeconds |
integer |
Estimated travel time in seconds that does not include delays on the route due to traffic conditions. |
durationTrafficInSeconds |
integer |
The time that it takes, in seconds, to travel a corresponding |
routePathRange |
Refers to the range covered by a specific Leg of a route or path. |
The level of traffic congestion along the route. Note
: Only supported for driving travelMode
Name | Type | Description |
---|---|---|
Heavy |
string |
Heavy. |
Medium |
string |
Medium. |
Mild |
string |
Mild. |
None |
string |
None. |
Unknown |
string |
Unknown. |
The type of real-time traffic data used to generate the route.
Name | Type | Description |
---|---|---|
Closure |
string |
Real-time closure data used, if applicable. |
Flow |
string |
Real-time traffic speeds used to calculate travel time. |
FlowAndClosure |
string |
Flow and Closure. |
None |
string |
None. |
The mode of travel for the requested route. If not defined, the default value is "driving" that returns the route optimized for cars.
Note
: For truck travelMode, the requested truck route may not be available for the entire route. Where the truck route is not available for a particular section, the travelMode element of the response for that section will be "other".
Example: "travelMode":"driving"
Name | Type | Description |
---|---|---|
driving |
string |
The returned routes are optimized for cars. |
truck |
string |
The returned routes are optimized for large size trucks based on the vehicle specification. |
walking |
string |
The returned routes are optimized for pedestrians, including the use of sidewalks. |
Types of cargo that may be classified as hazardous materials and restricted from some roads. Available vehicleLoadType values are US Hazmat classes 1 through 9, plus generic classifications for use in other countries. Values beginning with USHazmat are for US routing while otherHazmat should be used for all other countries. vehicleLoadType supports multiple values in a request.
Name | Type | Description |
---|---|---|
USHazmatClass1 |
string |
Explosives |
USHazmatClass2 |
string |
Compressed gas |
USHazmatClass3 |
string |
Flammable liquids |
USHazmatClass4 |
string |
Flammable solids |
USHazmatClass5 |
string |
Oxidizers |
USHazmatClass6 |
string |
Poisons |
USHazmatClass7 |
string |
Radioactive |
USHazmatClass8 |
string |
Corrosives |
USHazmatClass9 |
string |
Miscellaneous |
otherHazmatExplosive |
string |
Explosives |
otherHazmatGeneral |
string |
Miscellaneous |
otherHazmatHarmfulToWater |
string |
Harmful to water |
Vehicle attributes are specified inside of a vehicleSpec. Different regions may have different definitions for the truck classification and types, e.g., light truck, medium truck, heavy truck, etc. To get the most accurate results of the route restrictions based on the truck specs, specify the vehicle attributes.
Note
: Only supported for truck travelMode.
Name | Type | Default value | Description |
---|---|---|---|
axleCount |
integer |
0 |
Number of axles on the vehicle. A value of 0 means that axle restrictions are not considered. |
axleWeight |
integer |
0 |
Weight per axle of the vehicle in kg. A value of 0 means that weight restrictions per axle are not considered. |
height |
number |
0 |
Height of the vehicle in meters. A value of 0 means that height restrictions are not considered. |
isVehicleCommercial |
boolean |
False |
Whether the vehicle is used for commercial purposes. Commercial vehicles may not be allowed to drive on some roads. |
length |
number |
0 |
Length of the vehicle in meters. A value of 0 means that length restrictions are not considered. |
loadType |
Types of cargo that may be classified as hazardous materials and restricted from some roads. Available vehicleLoadType values are US Hazmat classes 1 through 9, plus generic classifications for use in other countries. Values beginning with USHazmat are for US routing while otherHazmat should be used for all other countries. vehicleLoadType supports multiple values in a request. |
||
maxSpeed |
integer |
0 |
Maximum speed of the vehicle in km/hour. The max speed in the vehicle profile is used to check whether a vehicle is allowed on motorways. A value of 0 means that an appropriate value for the vehicle will be determined and applied during route planning. A non-zero value may be overridden during route planning. For example, the current traffic flow is 60 km/hour. If the vehicle maximum speed is set to 50 km/hour, the routing engine will consider 60 km/hour as this is the current situation. If the maximum speed of the vehicle is provided as 80 km/hour but the current traffic flow is 60 km/hour, then routing engine will again use 60 km/hour. |
weight |
integer |
0 |
Weight of the vehicle in kilograms. A value of 0 means that weight restrictions are not considered. |
width |
number |
0 |
Width of the vehicle in meters. A value of 0 means that width restrictions are not considered. |
Specifies the properties of a ViaWaypoint
which is a waypoint that must be passed through or visited along a route or trip.
Name | Type | Description |
---|---|---|
names |
string[] |
A street, highway or intersection where the maneuver occurs. If the maneuver is complex, there may be more than one name field in the details collection. The name field may also have no value. This can occur if the name is not known or if a street, highway or intersection does not have a name. |
order |
Sequence for visiting waypoints and viaWaypoints. |
|
routePathPoint |
Refers to the index of a point within a specific Leg of a route. |
|
type |
string:
Via |
Output type. |
Specifies the properties of a Waypoint which is a specific location or point along a route or trip that serves as a reference or stopping point.
Name | Type | Default value | Description |
---|---|---|---|
compassDirection |
string |
The direction of travel associated with a maneuver on a route, such as south or southwest. |
|
distanceInMeters |
number |
The physical distance in meters covered by this route step. |
|
durationInSeconds |
integer |
The time that it takes, in seconds, to travel a corresponding |
|
exitIdentifier |
string |
The name or number of the exit associated with this route step. |
|
instruction |
A description of a maneuver in a set of directions. |
||
order |
Sequence for visiting waypoints and viaWaypoints. |
||
routePathPoint |
Refers to the index of a point within a specific Leg of a route. |
||
sideOfStreet |
The side of the street where the destination is found based on the arrival direction. This field applies to the last maneuverPoint only. |
||
signs |
string[] |
Signage text for the route. There may be more than one sign value. |
|
steps |
Step[] |
Steps between two consecutive maneuver points. |
|
towardsRoadName |
string |
The name of the street that the route goes towards in the first |
|
travelMode | driving |
The mode of travel for the route path in the response. |
|
type |
string:
Waypoint |
Output type. |