Route - Post Route Matrix Async

The Route Matrix Async API is an HTTP POST request that allows calculation of a matrix of route summaries for a set of routes defined by origin and destination locations by using an asynchronous (async) request. For every given origin, the service calculates the cost of routing from that origin to every given destination. The set of origins and the set of destinations can be thought of as the column and row headers of a table and each cell in the table contains the costs of routing from the origin to the destination for that cell. Route Matrices can be calculated for driving, walking and truck routes.

Route Matrices are used in several different types of applications, most commonly to solve the Traveling Salesman Problem (TSP) and Vehicle Routing Problem (VRP). For each origin-destination pair in the matrix, the travel time and distance are returned. You can use the computed costs to determine which detailed routes to calculate using the Route Directions API.

The maximum size of a matrix for async request is 50000 (the number of origins multiplied by the number of destinations).

Submit Asynchronous Route Matrix Request

The Asynchronous API is appropriate for processing big volumes of relatively complex routing requests. When you make a request by using async request, by default the service returns a 202 response code along a URL in the operation-Location field of the response header with the Azure Maps geography endpoint `{geography}.atlas.microsoft.com. This URL should be checked periodically until the status is Succeeded.

The maximum size of a matrix for this API is 50000 (the number of origins multiplied by the number of destinations). With that constraint in mind, examples of possible matrix dimensions are: 500x100, 100x100, 280x170. 100x50 (it does not need to be square).

The asynchronous responses are stored for 24 hours. The redirect URL returns a 404 response if used after the expiration period.

POST https://atlas.microsoft.com/route/matrix:async?api-version=2025-01-01&subscription-key={subscription-key}

Here's a typical sequence of asynchronous operations:

1. Client sends a Route Matrix POST request to Azure Maps

2. The server will respond with one of the following:

   HTTP 202 Accepted - Route Matrix request has been accepted.

   HTTP Error - There was an error processing your Route Matrix request. This could either be a 400 Bad Request or any other Error status code.

3. If the Matrix Route request was accepted successfully, the operation-___location header in the response contains the URL to get the status of the request. This status URI looks like the following:

  GET https://atlas.microsoft.com/route/operations/{id}?api-version=2025-01-01?subscription-key={subscription-key}

4. Client issues a GET request on the resultUrl obtained in Step 3 to get the results

  GET https://atlas.microsoft.com/route/operations/{id}/result?api-version=2025-01-01?subscription-key={subscription-key}

API Limitations

The asynchronous processing of matrix is best suited for larger matrices that require heavy route calculation. The following limitation is applicable to the asynchronous requests. If none of the rows in the following table match the request's parameters, the request does not meet the requirements and will not be processed.

POST https://atlas.microsoft.com/route/matrix:async?api-version=2025-01-01

URI Parameters

Request Header

Media Types: "application/geo+json"

Request Body

Media Types: "application/geo+json"

Responses

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.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

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

Submit an asynchronous request for matrix

POST https://atlas.microsoft.com/route/matrix:async?api-version=2025-01-01

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPoint",
        "coordinates": [
          [
            9.15049,
            45.458545
          ],
          [
            11.050541,
            45.403337
          ]
        ]
      },
      "properties": {
        "pointType": "origins"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPoint",
        "coordinates": [
          [
            11.499931,
            48.149853
          ],
          [
            14.538226,
            50.033688
          ]
        ]
      },
      "properties": {
        "pointType": "destinations"
      }
    }
  ],
  "departAt": "2022-12-19T16:39:57+01:00",
  "optimizeRoute": "fastest",
  "traffic": "historical",
  "travelMode": "truck",
  "avoid": [
    "unpavedRoads"
  ]
}

Operation-Location: https://atlas.microsoft.com/route/operations/bc3f9365-3ee0-4564-aa27-825016325557?api-version=2025-01-01

Definitions

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.

GeoJsonMultiPoint

A valid GeoJSON MultiPoint geometry type. Please refer to RFC 7946 for details.

InputRouteMatrixFeaturesItem

Specifies the input origin and destination points and additional properties for the GeoJSON MultiPoint feature object. Refer to RFC 7946 for details.

InputRouteMatrixProperties

Specifies the properties object for the input matrix.

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.

RouteMatrixAsyncOptimizeRouteEnum

Specifies the parameter to use to optimize the route. If not defined, the default is "fastest" which returns the route to minimize the travel time.

Example: "optimizeRoute":"shortest"

RouteMatrixAsyncRequest

Use to get a route matrix showing the travel time and distance for all possible pairs in a list of origins and destination. GeoJSON feature object and additional properties. Refer to RFC 7946 for details.

RouteMatrixAvoidEnum

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.

RouteMatrixTrafficEnum

Specifies how traffic is considered for computing routes.

Default value: historical

RouteMatrixTravelModeEnum

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

Example: "travelMode":"driving"

RouteMatrixTypeEnum

Specifies the origin MultiPoint type and destination MultiPoint type for the input matrix.

RouteMatrixVehicleSpec

Specifies the vehicle attributes such as vehicle height, weight, max speed, type of cargo, etc. to consider when calculating the route matrix. This helps avoid low bridge clearances, road restrictions, difficult right turns to provide the optimized 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.