Route - Post Route Range

Reference

Service:: Maps

API Version:: 2024-07-01-preview

Applies to: see pricing tiers.

The Route Range API creates a polygon that depicts the area reachable from a given location within a certain threshold based on the specified time or distance budget. 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 spatial filtering to search for features of interest within the provided Isochrone.

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. See the Preview Supplemental Terms for additional details.

POST https://atlas.microsoft.com/route/range?api-version=2024-07-01-preview

URI Parameters

Name	In	Required	Type	Description
api-version	query	True	string	Version number of Azure Maps API.

Request Header

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.

Request Body

Media Types: "application/geo+json"

Name	Required	Type	Description
geometry	True	RouteRangePointGeometry	Specifies the `GeoJSON` Point Geometry object. Refer to RFC 7946 for details.
properties	True	InputRouteRangeProperties	Specifies the parameters to use for the calculation of isochrone polygon.
type	True	FeaturesItemTypeEnum	Specifies the `GeoJSON` type. The only supported object type is Feature. For more information, see RFC 7946.

Responses

Name	Type	Description
200 OK	RouteRangeResponse	OK Media Types: "application/geo+json", "application/json"
Other Status Codes	MapsErrorResponse	An unexpected error occurred. Media Types: "application/geo+json", "application/json" Headers x-ms-error-code: string

Name

Type

Description

200 OK

RouteRangeResponse

Media Types: "application/geo+json", "application/json"

Other Status Codes

MapsErrorResponse

An unexpected error occurred.

Media Types: "application/geo+json", "application/json"

Headers

x-ms-error-code: string

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.

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

Scopes

Name	Description
https://atlas.microsoft.com/.default	https://atlas.microsoft.com/.default

subscription-key

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

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 the specified conditions

Sample request

HTTP

POST https://atlas.microsoft.com/route/range?api-version=2024-07-01-preview

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [
      5.86605,
      50.9745
    ]
  },
  "properties": {
    "timeBudgetInSec": 6000
  }
}

Sample response

Status code:: 200

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          5.86605,
          50.9745
        ]
      },
      "properties": {
        "type": "center"
      }
    },
    {
      "type": "Feature",
      "bbox": [
        3.62838,
        49.83259,
        7.9826,
        52.25674
      ],
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              5.73602,
              52.03704
            ],
            [
              5.59435,
              52.09456
            ],
            [
              5.42279,
              52.16815
            ],
            [
              5.21276,
              52.25047
            ],
            [
              5.15355,
              52.21374
            ],
            [
              4.96687,
              52.25674
            ],
            [
              4.739,
              52.07834
            ],
            [
              4.72513,
              52.05647
            ],
            [
              4.53237,
              51.94553
            ],
            [
              4.31165,
              51.70119
            ],
            [
              4.28917,
              51.5837
            ],
            [
              3.82685,
              51.48463
            ],
            [
              3.62838,
              51.21096
            ],
            [
              3.89244,
              50.6814
            ],
            [
              3.93493,
              50.66791
            ],
            [
              3.98156,
              50.49042
            ],
            [
              4.47995,
              50.30944
            ],
            [
              4.60502,
              50.24448
            ],
            [
              4.89999,
              50.24467
            ],
            [
              5.04206,
              50.08735
            ],
            [
              5.23042,
              49.99214
            ],
            [
              5.40994,
              49.88478
            ],
            [
              5.46178,
              49.85797
            ],
            [
              5.7196,
              49.86279
            ],
            [
              5.74151,
              49.83259
            ],
            [
              5.9387,
              50.22239
            ],
            [
              6.08535,
              50.0011
            ],
            [
              6.12089,
              50.04616
            ],
            [
              6.28373,
              50.09472
            ],
            [
              6.51654,
              49.95863
            ],
            [
              6.61034,
              50.00485
            ],
            [
              6.70295,
              50.00587
            ],
            [
              6.65865,
              50.2947
            ],
            [
              6.79276,
              50.36903
            ],
            [
              7.32163,
              50.31614
            ],
            [
              7.58782,
              50.36737
            ],
            [
              7.7626,
              50.46919
            ],
            [
              7.9826,
              50.96246
            ],
            [
              7.55924,
              51.07086
            ],
            [
              7.58138,
              51.36614
            ],
            [
              7.67861,
              51.52015
            ],
            [
              7.35175,
              51.65781
            ],
            [
              7.21664,
              51.81916
            ],
            [
              7.0467,
              51.9587
            ],
            [
              6.67267,
              51.82713
            ],
            [
              6.48424,
              51.81133
            ],
            [
              6.27316,
              51.9368
            ],
            [
              6.14452,
              52.01701
            ],
            [
              6.09312,
              52.20847
            ],
            [
              6.01297,
              52.23705
            ],
            [
              5.86605,
              50.9745
            ],
            [
              5.73602,
              52.03704
            ]
          ]
        ]
      },
      "properties": {
        "type": "boundary"
      }
    }
  ]
}

Definitions

Name	Description
AdrTunnelRestrictionCodeEnum	The ADR tunnel restriction code. ADR is a European agreement concerning the international carriage of dangerous goods by road. The ADR tunnel restriction code is used to determine whether a vehicle is allowed to pass through a tunnel with restrictions on the carriage of dangerous goods.
FeaturesItemTypeEnum	Specifies the `GeoJSON` type. The only supported object type is Feature. For more information, see RFC 7946.
FeatureTypeEnum	Specifies the `GeoJSON` type. The only supported object type is `FeatureCollection`. For more information, see RFC 7946.
InputRouteRangeProperties	Specifies the parameters to use for the calculation of isochrone polygon.
MapsErrorDetail	The error detail.
MapsErrorResponse	Common error response for Azure Maps APIs to return error details for failed operations.
MapsInnerError	An object containing more specific information than the current object about the error.
RouteRangeAvoidEnum	Specifies restrictions that the route calculation should honor when determining the reachable locations. Avoid supports multiple values in a request. Example: "avoid": ["limitedAccessHighways", "tollRoads"]
RouteRangeFeatureProperties	Route Ranges properties.
RouteRangeFeaturesItem	GeoJSON feature object that contains Geometry object and additional properties of the route.
RouteRangeOptimizeRouteEnum	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"
RouteRangePointGeometry	Specifies the `GeoJSON` Point Geometry object. Refer to RFC 7946 for details.
RouteRangePolygonGeometry	Specifies the `GeoJSON` Polygon Geometry object. Refer to RFC 7946 for details.
RouteRangeRequest	Specifies the starting point for range calculation. `GeoJSON` feature object and additional properties. Refer to RFC 7946 for details.
RouteRangeResponse	This object is returned from a successful call.
RouteRangeTravelModeEnum	Specifies the travel profile to consider when calculating the range polygon. If not specified, the default value is "driving". Example: "travelMode":"driving"
RouteRangeTypeEnum	The feature types for the feature objects returned in the response.
RouteRangeVehicleSpec	Specifies the vehicle attributes such as vehicle height, weight, max speed, type of cargo, etc. to consider when calculating the reachable locations. This helps avoid low bridge clearances, road restrictions, difficult right turns to provide the optimized truck route based on the vehicle specifications. Vehicle attributes are specified within the vehicleSpec property.
VehicleLoadTypeEnum	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.

AdrTunnelRestrictionCodeEnum

The ADR tunnel restriction code. ADR is a European agreement concerning the international carriage of dangerous goods by road. The ADR tunnel restriction code is used to determine whether a vehicle is allowed to pass through a tunnel with restrictions on the carriage of dangerous goods.

Name	Type	Description
B	string	Vehicles with code B are restricted from roads with ADR tunnel categories B, C, D, and E.
C	string	Vehicles with code C are restricted from roads with ADR tunnel categories C, D, and E
D	string	Vehicles with code D are restricted from roads with ADR tunnel categories D and E.
E	string	Vehicles with code E are restricted from roads with ADR tunnel category E.

FeaturesItemTypeEnum

Specifies the GeoJSON type. The only supported object type is Feature. For more information, see RFC 7946.

Name	Type	Description
Feature	string	Specifies the `GeoJSON` Feature object type.

FeatureTypeEnum

Specifies the GeoJSON type. The only supported object type is FeatureCollection. For more information, see RFC 7946.

Name	Type	Description
FeatureCollection	string	Specifies the `GeoJSON` `FeatureCollection` object type.

InputRouteRangeProperties

Specifies the parameters to use for the calculation of isochrone polygon.

Name	Type	Default value	Description
avoid	RouteRangeAvoidEnum[]		Specifies restrictions that the route calculation should honor when determining the reachable locations. Avoid supports multiple values in a request. Example: "avoid": ["limitedAccessHighways", "tollRoads"]
departAt	string		The date and time of departure from the origin point formatted as a dateTime value defined by RFC 3339, section 5.6. When a time zone offset is not specified, UTC will be assumed. If the `departAt` is not set, the default value is the current time. Example: "departAt": "2023-06-01T09:30:00.000-07:00"
distanceBudgetInMeters	number		The distance budget specifies the maximum range in meters which can be travelled from the origin waypoint. It cannot be set when `timeBudgetInSec` is specified. When `isSimplifiedPolygon` is false, the maximum distance supported is 360,000 meters; otherwise, it is 50,000,000 meters. Example: "distanceBudgetInMeters":5000
isSimplifiedPolygon	boolean	false	Use this to specify if you need simplified polygons that reduces the number of polygon vertices while preserving the shape. The API returns high definition polygon by default.
optimizeRoute	RouteRangeOptimizeRouteEnum	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"
timeBudgetInSec	number		The time budget specifies the maximum time in seconds available for travel, defining how far one can go within this time constraint from the origin waypoint. It cannot be set when `distanceBudgetInMeters` is specified. When `isSimplifiedPolygon` is false, the maximum time supported is 14,400 seconds; otherwise, it is 10,000,000 seconds. Example: "timeBudgetInSec":3600
travelMode	RouteRangeTravelModeEnum	driving	Specifies the travel profile to consider when calculating the range polygon. If not specified, the default value is "driving". Example: "travelMode":"driving"
vehicleSpec	RouteRangeVehicleSpec		Specifies the vehicle attributes such as vehicle height, weight, max speed, type of cargo, etc. to consider when calculating the reachable locations. This helps avoid low bridge clearances, road restrictions, difficult right turns to provide the optimized truck route based on the vehicle specifications. Vehicle attributes are specified within the vehicleSpec property.

MapsErrorDetail

The error detail.

Name	Type	Description
code	string	One of a server-defined set of error codes.
details	MapsErrorDetail[]	An array of details about specific errors that led to this reported error.
innererror	MapsInnerError	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.

MapsErrorResponse

Common error response for Azure Maps APIs to return error details for failed operations.

Name	Type	Description
error	MapsErrorDetail	The error detail.

MapsInnerError

An object containing more specific information than the current object about the error.

Name	Type	Description
code	string	The error code.
innererror	MapsInnerError	An object containing more specific information than the current object about the error.

RouteRangeAvoidEnum

Specifies restrictions that the route calculation should honor when determining the reachable locations. Avoid supports multiple values in a request.

Example: "avoid": ["limitedAccessHighways", "tollRoads"]

Name	Type	Description
borderCrossings	string	Avoids crossing country borders in the route.
carTrains	string	Avoids car trains.
carpools	string	Avoids routes that require use of carpool.
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.

RouteRangeFeatureProperties

Route Ranges properties.

Name	Type	Description
type	RouteRangeTypeEnum	The feature types for the feature objects returned in the response.

RouteRangeFeaturesItem

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	RouteRangeGeometry: RouteRangePointGeometry RouteRangePolygonGeometry	A valid `GeoJSON` Geometry object. Please refer to RFC 7946 for details.
properties	RouteRangeFeatureProperties	Route Ranges properties.
type	FeaturesItemTypeEnum	Specifies the `GeoJSON` type. The only supported object type is Feature. For more information, see RFC 7946.

RouteRangeOptimizeRouteEnum

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
fastestWithTraffic	string	The route is calculated to minimize the time using current traffic information. `Note`: Only supported for driving and truck travelMode.
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.

RouteRangePointGeometry

Specifies the GeoJSON Point Geometry object. Refer to RFC 7946 for details.

Name	Type	Description
coordinates	number[]	A `Position` is an array of numbers with two or more elements. The first two elements are longitude and latitude, precisely in that order. Altitude/Elevation is an optional third element. Please refer to RFC 7946 for details.
type	string: Point	Specifies the geometry type for the `GeoJSON` Geometry object. Refer to RFC 7946 for details.

RouteRangePolygonGeometry

Specifies the GeoJSON Polygon Geometry object. Refer to RFC 7946 for details.

Name	Type	Description
coordinates	number[]	Coordinates for the `GeoJson Polygon` geometry type.
type	string: Polygon	Specifies the geometry type for the `GeoJSON` Geometry object. Refer to RFC 7946 for details.

RouteRangeRequest

Specifies the starting point for range calculation. GeoJSON feature object and additional properties. Refer to RFC 7946 for details.

Name	Type	Description
geometry	RouteRangePointGeometry	Specifies the `GeoJSON` Point Geometry object. Refer to RFC 7946 for details.
properties	InputRouteRangeProperties	Specifies the parameters to use for the calculation of isochrone polygon.
type	FeaturesItemTypeEnum	Specifies the `GeoJSON` type. The only supported object type is Feature. For more information, see RFC 7946.

RouteRangeResponse

This object is returned from a successful call.

Name	Type	Description
features	RouteRangeFeaturesItem[]	`GeoJSON` feature object that contains Geometry object and additional properties. Refer to RFC 7946, Section 3.2 for details.
type	FeatureTypeEnum	Specifies the `GeoJSON` type. The only supported object type is `FeatureCollection`. For more information, see RFC 7946.

RouteRangeTravelModeEnum

Specifies the travel profile to consider when calculating the range polygon. If not specified, the default value is "driving".

Example: "travelMode":"driving"

Name	Type	Description
driving	string	Routing profile suitable for cars are used for range polygon calculation.
truck	string	Routing profile suitable for commercial vehicles like trucks are used for range polygon calculation.

RouteRangeTypeEnum

The feature types for the feature objects returned in the response.

Name	Type	Description
boundary	string	The boundary feature type represents the range polygon.
center	string	The center point feature type represents the point used for the range polygon calculation.

RouteRangeVehicleSpec

Specifies the vehicle attributes such as vehicle height, weight, max speed, type of cargo, etc. to consider when calculating the reachable locations. This helps avoid low bridge clearances, road restrictions, difficult right turns to provide the optimized truck route based on the vehicle specifications. Vehicle attributes are specified within the vehicleSpec property.

Name	Type	Default value	Description
adrTunnelRestrictionCode	AdrTunnelRestrictionCodeEnum		The ADR tunnel restriction code. ADR is a European agreement concerning the international carriage of dangerous goods by road. The ADR tunnel restriction code is used to determine whether a vehicle is allowed to pass through a tunnel with restrictions on the carriage of dangerous goods.
axleCount	integer		The number of axles on the vehicle.
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	VehicleLoadTypeEnum[]		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.

VehicleLoadTypeEnum

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

Share via

Route - Post Route Range

URI Parameters

Request Header

Request Body

Responses

Security

AADToken

Scopes

subscription-key

SAS Token

Examples

Successfully retrieve a set of locations that can be reached from the origin point based on the specified conditions

Sample request

Sample response

Definitions

AdrTunnelRestrictionCodeEnum

FeaturesItemTypeEnum

FeatureTypeEnum

InputRouteRangeProperties

MapsErrorDetail

MapsErrorResponse

MapsInnerError

RouteRangeAvoidEnum

RouteRangeFeatureProperties

RouteRangeFeaturesItem

RouteRangeOptimizeRouteEnum

RouteRangePointGeometry

RouteRangePolygonGeometry

RouteRangeRequest

RouteRangeResponse

RouteRangeTravelModeEnum

RouteRangeTypeEnum

RouteRangeVehicleSpec

VehicleLoadTypeEnum

Additional resources