---
title: "POST /route/matrix:async"
method: POST
path: "/route/matrix:async"
---

# POST /route/matrix:async

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

| Max matrix size  | Max number of origins | Max number of destinations  |
Additional limits |

|------------------|-----------------------|-----------------------------|-------------------|
| 2500             | 1000                  | 1000                        | All
origins and destinations should be contained in an axis-aligned 400 km x 400 km
bounding box. Otherwise some matrix cells will be resolved as OUT_OF_REGION.  |
| 50,000           | 10,000                | 10,000                      | -
`departAt` or `arriveAt` must be any.<br>- `traffic` must be historical.<br/>-
`optimizeRoute` must be fastest.<br/>- `travelMode` must be
either driving or truck. <br/>- No other parameters can be used explicitly.  |

## Query parameters

- `api-version` string, required

## Headers

- `x-ms-client-id` string

## Response `202`

The request has been accepted for processing, but processing has not yet completed.

## Other responses

- `default` — An unexpected error response.

---

[API](https://skmtc.net/azure/apis/maps-route.md) · [All operations](https://skmtc.net/azure/apis/maps-route/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/azure/maps-route/versions/4b7b4a919999/schema)