Route - Get Route Range
Use to create a map that depicts the area accessible from a given point within a certain threshold based on time, distance or fuel capacity.
The Get Route Range
(Isochrone) API is an HTTP GET
request that will calculate a set of locations that can be reached from the origin point based on fuel, energy, time or distance budget that is specified. A polygon boundary (or Isochrone) is returned in a counterclockwise orientation as well as the precise polygon center which was the result of the origin point.
The returned polygon can be used for further processing such as Search Inside Geometry to search for POIs within the provided isochrone.
GET https://atlas.microsoft.com/route/range/{format}?api-version=1.0&query={query}
GET https://atlas.microsoft.com/route/range/{format}?api-version=1.0&query={query}&fuelBudgetInLiters={fuelBudgetInLiters}&energyBudgetInkWh={energyBudgetInkWh}&timeBudgetInSec={timeBudgetInSec}&distanceBudgetInMeters={distanceBudgetInMeters}&departAt={departAt}&routeType={routeType}&traffic={traffic}&avoid={avoid}&travelMode={travelMode}&hilliness={hilliness}&windingness={windingness}&vehicleAxleWeight={vehicleAxleWeight}&vehicleWidth={vehicleWidth}&vehicleHeight={vehicleHeight}&vehicleLength={vehicleLength}&vehicleMaxSpeed={vehicleMaxSpeed}&vehicleWeight={vehicleWeight}&vehicleCommercial={vehicleCommercial}&vehicleLoadType={vehicleLoadType}&vehicleEngineType={vehicleEngineType}&constantSpeedConsumptionInLitersPerHundredkm={constantSpeedConsumptionInLitersPerHundredkm}¤tFuelInLiters={currentFuelInLiters}&auxiliaryPowerInLitersPerHour={auxiliaryPowerInLitersPerHour}&fuelEnergyDensityInMJoulesPerLiter={fuelEnergyDensityInMJoulesPerLiter}&accelerationEfficiency={accelerationEfficiency}&decelerationEfficiency={decelerationEfficiency}&uphillEfficiency={uphillEfficiency}&downhillEfficiency={downhillEfficiency}&constantSpeedConsumptionInkWhPerHundredkm={constantSpeedConsumptionInkWhPerHundredkm}¤tChargeInkWh={currentChargeInkWh}&maxChargeInkWh={maxChargeInkWh}&auxiliaryPowerInkW={auxiliaryPowerInkW}
URI Parameters
Name | In | Required | Type | Description |
---|---|---|---|---|
format
|
path | True |
Desired format of the response. Value can be either json or xml. |
|
api-version
|
query | True |
string |
Version number of Azure Maps API. |
query
|
query | True |
number[] |
The Coordinate from which the range calculation should start. |
acceleration
|
query |
number double |
Specifies the efficiency of converting chemical energy stored in fuel to kinetic energy when the vehicle accelerates (i.e. KineticEnergyGained/ChemicalEnergyConsumed). ChemicalEnergyConsumed is obtained by converting consumed fuel to chemical energy using fuelEnergyDensityInMJoulesPerLiter. Must be paired with decelerationEfficiency. The range of values allowed are 0.0 to 1/decelerationEfficiency. Sensible Values : for Combustion Model : 0.33, for Electric Model : 0.66 |
|
auxiliary
|
query |
number double |
Specifies the amount of power consumed for sustaining auxiliary systems, in kilowatts (kW). It can be used to specify consumption due to devices and systems such as AC systems, radio, heating, etc. Sensible Values : 1.7 |
|
auxiliary
|
query |
number double |
Specifies the amount of fuel consumed for sustaining auxiliary systems of the vehicle, in liters per hour. It can be used to specify consumption due to devices and systems such as AC systems, radio, heating, etc. Sensible Values : 0.2 |
|
avoid
|
query |
Specifies something that the route calculation should try to avoid when determining the route. Can be specified multiple times in one request, for example, '&avoid=motorways&avoid=tollRoads&avoid=ferries'. In Route Range requests, the value alreadyUsedRoads must not be used. |
||
constant
|
query |
string |
Specifies the speed-dependent component of consumption. Provided as an unordered list of speed/consumption-rate pairs. The list defines points on a consumption curve. Consumption rates for speeds not in the list are found as follows:
The list must contain between 1 and 25 points (inclusive), and may not contain duplicate points for the same speed. If it only contains a single point, then the consumption rate of that point is used without further processing. Consumption specified for the largest speed must be greater than or equal to that of the penultimate largest speed. This ensures that extrapolation does not lead to negative consumption rates. Similarly, consumption values specified for the two smallest speeds in the list cannot lead to a negative consumption rate for any smaller speed. The valid range for the consumption values(expressed in kWh/100km) is between 0.01 and 100000.0. Sensible Values : 50,8.2:130,21.3 This parameter is required for Electric consumption model. |
|
constant
|
query |
string |
Specifies the speed-dependent component of consumption. Provided as an unordered list of colon-delimited speed & consumption-rate pairs. The list defines points on a consumption curve. Consumption rates for speeds not in the list are found as follows:
The list must contain between 1 and 25 points (inclusive), and may not contain duplicate points for the same speed. If it only contains a single point, then the consumption rate of that point is used without further processing. Consumption specified for the largest speed must be greater than or equal to that of the penultimate largest speed. This ensures that extrapolation does not lead to negative consumption rates. Similarly, consumption values specified for the two smallest speeds in the list cannot lead to a negative consumption rate for any smaller speed. The valid range for the consumption values(expressed in l/100km) is between 0.01 and 100000.0. Sensible Values : 50,6.3:130,11.5 Note : This parameter is required for The Combustion Consumption Model. |
|
current
|
query |
number double |
Specifies the current electric energy supply in kilowatt hours (kWh). This parameter co-exists with maxChargeInkWh parameter. The range of values allowed are 0.0 to maxChargeInkWh. Sensible Values : 43 |
|
current
|
query |
number double |
Specifies the current supply of fuel in liters. Sensible Values : 55 |
|
deceleration
|
query |
number double |
Specifies the efficiency of converting kinetic energy to saved (not consumed) fuel when the vehicle decelerates (i.e. ChemicalEnergySaved/KineticEnergyLost). ChemicalEnergySaved is obtained by converting saved (not consumed) fuel to energy using fuelEnergyDensityInMJoulesPerLiter. Must be paired with accelerationEfficiency. The range of values allowed are 0.0 to 1/accelerationEfficiency. Sensible Values : for Combustion Model : 0.83, for Electric Model : 0.91 |
|
depart
|
query |
string date-time |
The date and time of departure from the origin point formatted as a
Examples:
The |
|
distance
|
query |
number double |
Distance budget in meters that determines maximal range which can be travelled using driving distance. The Consumption Model will only affect the range when routeType is eco. |
|
downhill
|
query |
number double |
Specifies the efficiency of converting potential energy to saved (not consumed) fuel when the vehicle loses elevation (i.e. ChemicalEnergySaved/PotentialEnergyLost). ChemicalEnergySaved is obtained by converting saved (not consumed) fuel to energy using fuelEnergyDensityInMJoulesPerLiter. Must be paired with uphillEfficiency. The range of values allowed are 0.0 to 1/uphillEfficiency. Sensible Values : for Combustion Model : 0.51, for Electric Model : 0.73 |
|
energy
|
query |
number double |
Electric energy budget in kilowatt hours (kWh) that determines maximal range which can be travelled using the specified Electric Consumption Model. |
|
fuel
|
query |
number double |
Fuel budget in liters that determines maximal range which can be travelled using the specified Combustion Consumption Model. |
|
fuel
|
query |
number double |
Specifies the amount of chemical energy stored in one liter of fuel in megajoules (MJ). It is used in conjunction with the *Efficiency parameters for conversions between saved or consumed energy and fuel. For example, energy density is 34.2 MJ/l for gasoline, and 35.8 MJ/l for Diesel fuel. This parameter is required if any *Efficiency parameter is set. Sensible Values : 34.2 |
|
hilliness
|
query |
Degree of hilliness for thrilling route. This parameter can only be used in conjunction with |
||
max
|
query |
number double |
Specifies the maximum electric energy supply in kilowatt hours (kWh) that may be stored in the vehicle's battery. This parameter co-exists with currentChargeInkWh parameter. Minimum value has to be greater than or equal to currentChargeInkWh. Sensible Values : 85 |
|
route
|
query |
The type of route requested. |
||
time
|
query |
number double |
Time budget in seconds that determines maximal range which can be travelled using driving time. The Consumption Model will only affect the range when routeType is eco. |
|
traffic
|
query |
boolean |
Possible values:
|
|
travel
|
query |
The mode of travel for the requested route. If not defined, default is 'car'. Note that the requested travelMode may not be available for the entire route. Where the requested travelMode is not available for a particular section, the travelMode element of the response for that section will be "other". Note that travel modes bus, motorcycle, taxi and van are BETA functionality. Full restriction data is not available in all areas. |
||
uphill
|
query |
number double |
Specifies the efficiency of converting chemical energy stored in fuel to potential energy when the vehicle gains elevation (i.e. PotentialEnergyGained/ChemicalEnergyConsumed). ChemicalEnergyConsumed is obtained by converting consumed fuel to chemical energy using fuelEnergyDensityInMJoulesPerLiter. Must be paired with downhillEfficiency. The range of values allowed are 0.0 to 1/downhillEfficiency. Sensible Values : for Combustion Model : 0.27, for Electric Model : 0.74 |
|
vehicle
|
query |
integer |
Weight per axle of the vehicle in kg. A value of 0 means that weight restrictions per axle are not considered. |
|
vehicle
|
query |
boolean |
Whether the vehicle is used for commercial purposes. Commercial vehicles may not be allowed to drive on some roads. |
|
vehicle
|
query |
Engine type of the vehicle. When a detailed Consumption Model is specified, it must be consistent with the value of vehicleEngineType. |
||
vehicle
|
query |
number double |
Height of the vehicle in meters. A value of 0 means that height restrictions are not considered. |
|
vehicle
|
query |
number double |
Length of the vehicle in meters. A value of 0 means that length restrictions are not considered. |
|
vehicle
|
query |
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/regions. Values beginning with USHazmat are for US routing while otherHazmat should be used for all other countries/regions. vehicleLoadType can be specified multiple times. This parameter is currently only considered for travelMode=truck. |
||
vehicle
|
query |
integer |
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.
|
|
vehicle
|
query |
integer |
Weight of the vehicle in kilograms.
Sensible Values : for Combustion Model : 1600, for Electric Model : 1900 |
|
vehicle
|
query |
number double |
Width of the vehicle in meters. A value of 0 means that width restrictions are not considered. |
|
windingness
|
query |
Level of turns for thrilling route. This parameter can only be used in conjunction with |
Request Header
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. |
Responses
Name | Type | Description |
---|---|---|
200 OK |
OK |
|
Other Status Codes |
An unexpected error occurred. |
Security
AADToken
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.
Notes
- 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
Scopes
Name | Description |
---|---|
https://atlas.microsoft.com/.default | https://atlas.microsoft.com/.default |
subscription-key
This is a shared key that is provisioned when you Create an Azure Maps account in the Azure portal or using PowerShell, CLI, Azure SDKs, or REST API.
With this key, any application can access all REST API. In other words, this key can be used as a master key in the account that they are issued in.
For publicly exposed applications, our recommendation is to use the confidential client applications approach to access Azure Maps REST APIs so your key can be securely stored.
Type:
apiKey
In:
query
SAS Token
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
Examples
Successfully retrieve a set of locations that can be reached from the origin point based on various conditions
Sample request
GET https://atlas.microsoft.com/route/range/json?api-version=1.0&query=50.97452,5.86605&timeBudgetInSec=6000
Sample response
{
"formatVersion": "0.0.1",
"reachableRange": {
"center": {
"latitude": 50.9745,
"longitude": 5.86605
},
"boundary": [
{
"latitude": 52.03704,
"longitude": 5.73602
},
{
"latitude": 52.09456,
"longitude": 5.59435
},
{
"latitude": 52.16815,
"longitude": 5.42279
},
{
"latitude": 52.25047,
"longitude": 5.21276
},
{
"latitude": 52.21374,
"longitude": 5.15355
},
{
"latitude": 52.25674,
"longitude": 4.96687
},
{
"latitude": 52.07834,
"longitude": 4.739
},
{
"latitude": 52.05647,
"longitude": 4.72513
},
{
"latitude": 51.94553,
"longitude": 4.53237
},
{
"latitude": 51.70119,
"longitude": 4.31165
},
{
"latitude": 51.5837,
"longitude": 4.28917
},
{
"latitude": 51.48463,
"longitude": 3.82685
},
{
"latitude": 51.21096,
"longitude": 3.62838
},
{
"latitude": 50.6814,
"longitude": 3.89244
},
{
"latitude": 50.66791,
"longitude": 3.93493
},
{
"latitude": 50.49042,
"longitude": 3.98156
},
{
"latitude": 50.30944,
"longitude": 4.47995
},
{
"latitude": 50.24448,
"longitude": 4.60502
},
{
"latitude": 50.24467,
"longitude": 4.89999
},
{
"latitude": 50.08735,
"longitude": 5.04206
},
{
"latitude": 49.99214,
"longitude": 5.23042
},
{
"latitude": 49.88478,
"longitude": 5.40994
},
{
"latitude": 49.85797,
"longitude": 5.46178
},
{
"latitude": 49.86279,
"longitude": 5.7196
},
{
"latitude": 49.83259,
"longitude": 5.74151
},
{
"latitude": 50.22239,
"longitude": 5.9387
},
{
"latitude": 50.0011,
"longitude": 6.08535
},
{
"latitude": 50.04616,
"longitude": 6.12089
},
{
"latitude": 50.09472,
"longitude": 6.28373
},
{
"latitude": 49.95863,
"longitude": 6.51654
},
{
"latitude": 50.00485,
"longitude": 6.61034
},
{
"latitude": 50.00587,
"longitude": 6.70295
},
{
"latitude": 50.2947,
"longitude": 6.65865
},
{
"latitude": 50.36903,
"longitude": 6.79276
},
{
"latitude": 50.31614,
"longitude": 7.32163
},
{
"latitude": 50.36737,
"longitude": 7.58782
},
{
"latitude": 50.46919,
"longitude": 7.7626
},
{
"latitude": 50.96246,
"longitude": 7.9826
},
{
"latitude": 51.07086,
"longitude": 7.55924
},
{
"latitude": 51.36614,
"longitude": 7.58138
},
{
"latitude": 51.52015,
"longitude": 7.67861
},
{
"latitude": 51.65781,
"longitude": 7.35175
},
{
"latitude": 51.81916,
"longitude": 7.21664
},
{
"latitude": 51.9587,
"longitude": 7.0467
},
{
"latitude": 51.82713,
"longitude": 6.67267
},
{
"latitude": 51.81133,
"longitude": 6.48424
},
{
"latitude": 51.9368,
"longitude": 6.27316
},
{
"latitude": 52.01701,
"longitude": 6.14452
},
{
"latitude": 52.20847,
"longitude": 6.09312
},
{
"latitude": 52.23705,
"longitude": 6.01297
}
]
}
}
Definitions
Name | Description |
---|---|
Effective |
Effective parameter or data used when calling this Route API. |
Error |
The resource management error additional info. |
Error |
The error detail. |
Error |
Error response |
Incline |
Degree of hilliness for thrilling route. This parameter can only be used in conjunction with |
Lat |
A location represented as a latitude and longitude. |
Response |
Desired format of the response. Value can be either json or xml. |
Route |
Specifies something that the route calculation should try to avoid when determining the route. Can be specified multiple times in one request, for example, '&avoid=motorways&avoid=tollRoads&avoid=ferries'. In Route Range requests, the value alreadyUsedRoads must not be used. |
Route |
Reachable Range |
Route |
This object is returned from a successful Route Reachable Range call |
Route |
Reports the effective settings used in the current call. |
Route |
The type of route requested. |
Travel |
The mode of travel for the requested route. If not defined, default is 'car'. Note that the requested travelMode may not be available for the entire route. Where the requested travelMode is not available for a particular section, the travelMode element of the response for that section will be "other". Note that travel modes bus, motorcycle, taxi and van are BETA functionality. Full restriction data is not available in all areas. |
Vehicle |
Engine type of the vehicle. When a detailed Consumption Model is specified, it must be consistent with the value of vehicleEngineType. |
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/regions. Values beginning with USHazmat are for US routing while otherHazmat should be used for all other countries/regions. vehicleLoadType can be specified multiple times. This parameter is currently only considered for travelMode=truck. |
Windingness |
Level of turns for thrilling route. This parameter can only be used in conjunction with |
EffectiveSetting
Effective parameter or data used when calling this Route API.
Name | Type | Description |
---|---|---|
key |
string |
Name of the parameter used. |
value |
string |
Value of the parameter used. |
ErrorAdditionalInfo
The resource management error additional info.
Name | Type | Description |
---|---|---|
info |
object |
The additional info. |
type |
string |
The additional info type. |
ErrorDetail
The error detail.
Name | Type | Description |
---|---|---|
additionalInfo |
The error additional info. |
|
code |
string |
The error code. |
details |
The error details. |
|
message |
string |
The error message. |
target |
string |
The error target. |
ErrorResponse
Error response
Name | Type | Description |
---|---|---|
error |
The error object. |
InclineLevel
Degree of hilliness for thrilling route. This parameter can only be used in conjunction with routeType
=thrilling.
Name | Type | Description |
---|---|---|
high |
string |
high |
low |
string |
low |
normal |
string |
normal |
LatLongPair
A location represented as a latitude and longitude.
Name | Type | Description |
---|---|---|
latitude |
number |
Latitude property |
longitude |
number |
Longitude property |
ResponseFormat
Desired format of the response. Value can be either json or xml.
Name | Type | Description |
---|---|---|
json |
string |
|
xml |
string |
RouteAvoidType
Specifies something that the route calculation should try to avoid when determining the route. Can be specified multiple times in one request, for example, '&avoid=motorways&avoid=tollRoads&avoid=ferries'. In Route Range requests, the value alreadyUsedRoads must not be used.
Name | Type | Description |
---|---|---|
alreadyUsedRoads |
string |
Avoids using the same road multiple times. Most useful in conjunction with |
borderCrossings |
string |
Avoids border crossings in route calculation. |
carpools |
string |
Avoids routes that require the use of carpool (HOV/High Occupancy Vehicle) lanes. |
ferries |
string |
Avoids ferries |
motorways |
string |
Avoids motorways |
tollRoads |
string |
Avoids toll roads. |
unpavedRoads |
string |
Avoids unpaved roads |
RouteRange
Reachable Range
Name | Type | Description |
---|---|---|
boundary |
Polygon boundary of the reachable range represented as a list of points. |
|
center |
Center point of the reachable range |
RouteRangeResult
This object is returned from a successful Route Reachable Range call
Name | Type | Description |
---|---|---|
formatVersion |
string |
Format Version property |
reachableRange |
Reachable Range |
|
report |
Reports the effective settings used in the current call. |
RouteReport
Reports the effective settings used in the current call.
Name | Type | Description |
---|---|---|
effectiveSettings |
Effective parameters or data used when calling this Route API. |
RouteType
The type of route requested.
Name | Type | Description |
---|---|---|
eco |
string |
A route balanced by economy and speed. |
fastest |
string |
The fastest route. |
shortest |
string |
The shortest route by distance. |
thrilling |
string |
Includes interesting or challenging roads and uses as few motorways as possible. You can choose the level of turns included and also the degree of hilliness. See the hilliness and windingness parameters for how to set this. There is a limit of 900 km on routes planned with |
TravelMode
The mode of travel for the requested route. If not defined, default is 'car'. Note that the requested travelMode may not be available for the entire route. Where the requested travelMode is not available for a particular section, the travelMode element of the response for that section will be "other". Note that travel modes bus, motorcycle, taxi and van are BETA functionality. Full restriction data is not available in all areas.
Name | Type | Description |
---|---|---|
bus |
string |
The returned routes are optimized for buses, including the use of bus only lanes. BETA functionality. |
car |
string |
The returned routes are optimized for cars. |
motorcycle |
string |
The returned routes are optimized for motorcycles. BETA functionality. |
taxi |
string |
The returned routes are optimized for taxis. BETA functionality. |
truck |
string |
The returned routes are optimized for commercial vehicles, like for trucks. |
van |
string |
The returned routes are optimized for vans. BETA functionality. |
VehicleEngineType
Engine type of the vehicle. When a detailed Consumption Model is specified, it must be consistent with the value of vehicleEngineType.
Name | Type | Description |
---|---|---|
combustion |
string |
Internal combustion engine. |
electric |
string |
Electric engine. |
VehicleLoadType
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/regions. Values beginning with USHazmat are for US routing while otherHazmat should be used for all other countries/regions. vehicleLoadType can be specified multiple times. This parameter is currently only considered for travelMode=truck.
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 |
WindingnessLevel
Level of turns for thrilling route. This parameter can only be used in conjunction with routeType
=thrilling.
Name | Type | Description |
---|---|---|
high |
string |
high |
low |
string |
low |
normal |
string |
normal |