Share via

Route - Post Route Range Batch

  • Reference
Service:
Maps
API Version:
2024-07-01-preview

Route Range Batch API

Applies to: see pricing tiers.

The Route Range Batch API sends batches of up to 100 queries as a single call to the Route Range API.

Important

By using this feature, you agree to the preview legal terms. See the Preview Supplemental Terms for additional details.

Submit Synchronous Batch Request

The Synchronous API is recommended for lightweight batch requests. When the service receives a request, it will respond as soon as the batch items are calculated and there will be no possibility to retrieve the results later. The Synchronous API will return a timeout error (a 408 response) if the request takes longer than 60 seconds. The number of batch items is limited to 100 for this API.

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

POST Body for Batch Request

To send the route range queries you will use a POST request where the request body will contain the batchItems array in json format and the Content-Type header will be set to application/json. Here's a sample request body containing 2 route_range queries:

{
  "batchItems": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          5.86605,
          50.9745
        ]
      },
      "properties": {
        "timeBudgetInSec": 6000
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          -122.201669,
          47.615076
        ]
      },
      "properties": {
        "timeBudgetInSec": 2000
      }
    }
  ]
}

A route range batchItem object can accept any of the supported snap to roads Request body

The batch should contain at least 1 query.

Batch Response Model

The batch response contains a summary component that indicates the totalRequests that were part of the original batch request and successfulRequests i.e. queries which were executed successfully. The batch response also includes a batchItems array which contains a response for each and every query in the batch request. The batchItems will contain the results in the exact same order the original queries were sent in the batch request. Each item is of one of the following types:

  • RouteRangeResponse - If the query completed successfully.

  • Error - If the query failed. The response will contain a code and a message in this case.

POST https://atlas.microsoft.com/route/range:batch?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

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

Name Type Description
batchItems

RouteRangeBatchRequestItem[]

The list of queries to process.

Responses

Name Type Description
200 OK

RouteRangeBatchResponse

Batch request successfully processed. The response body contains all the batch results.
Other Status Codes

MapsErrorResponse

An unexpected error occurred.

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

A Route Range Batch request containing 1 query

Sample request

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

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

Sample response

Status code:
200 
{
  "summary": {
    "successfulRequests": 1,
    "totalRequests": 2
  },
  "batchItems": [
    {
      "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"
          }
        }
      ]
    },
    {
      "error": {
        "code": "BadRequest",
        "message": "No routable road could be found near one or more specified points."
      }
    }
  ]
}

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.
ErrorAdditionalInfo

The resource management error additional info.
ErrorDetail

The error detail.
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"]
RouteRangeBatchRequestBody

The list of route range queries/requests to process. The list can contain a max of 100 queries and must contain at least 1 query.
RouteRangeBatchRequestItem

Batch Query object
RouteRangeBatchResponse

This object is returned from a successful Route Range Batch service call.
RouteRangeBatchResponseItem

Batch response item
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.
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.

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

ErrorAdditionalInfo[]

The error additional info.
code

string

The error code.
details

ErrorDetail[]

The error details.
message

string

The error message.
target

string

The error target.

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 traveled 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 500,000 meters.

Example: "distanceBudgetInMeters":5000
isSimplifiedPolygon

boolean

true

Use this to specify if you need simplified polygons that reduces the number of polygon vertices while preserving the shape. The API returns low 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 21,600 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.

RouteRangeBatchRequestBody

The list of route range queries/requests to process. The list can contain a max of 100 queries and must contain at least 1 query.

Name Type Description
batchItems

RouteRangeBatchRequestItem[]

The list of queries to process.

RouteRangeBatchRequestItem

Batch Query object

Name Type Description
geometry

RouteRangePointGeometry

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

string

Id of the request which would show in corresponding batchItem.
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.

RouteRangeBatchResponse

This object is returned from a successful Route Range Batch service call.

Name Type Description
batchItems

RouteRangeBatchResponseItem[]

Array containing the batch results.
summary.successfulRequests

integer

Number of successful requests in the batch
summary.totalRequests

integer

Total number of requests in the batch

RouteRangeBatchResponseItem

Batch response item

Name Type Description
error

ErrorDetail

The error detail.
features

RouteRangeFeaturesItem[]

GeoJSON feature object that contains Geometry object and additional properties. Refer to RFC 7946, Section 3.2 for details.
optionalId

string

Id of the request which would show in corresponding batchItem.
type

FeatureTypeEnum

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

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:

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.

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