Use to get a route matrix showing the travel time and distance for all possible pairs in a list of origins and destinations, using a synchronous request.

[!NOTE]

Azure Maps Route v1 service retirement

The Azure Maps Route v1 service is now deprecated and will be retired on 3/31/28. To avoid service disruptions, all calls to Route v1 service will need to be updated to use Route v2025-01-01 service by 3/31/28. For more information, see Migrate Azure Maps Route 1.0 APIs.

The Post Route Matrix Sync 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 a single synchronous (sync) request. To make an asynchronous (async) request, see Post Route Matrix. 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. As an example, let's say a food delivery company has 20 drivers and they need to find the closest driver to pick up the delivery from the restaurant. To solve this use case, they can call Matrix Route API.

For each route, the travel times and distances 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 700 and for sync request it's 100 (the number of origins multiplied by the number of destinations).

Submit Synchronous Route Matrix Request

If your scenario requires synchronous requests and the maximum size of the matrix is less than or equal to 100, you might want to make synchronous request. The maximum size of a matrix for this API is 100 (the number of origins multiplied by the number of destinations). With that constraint in mind, examples of possible matrix dimensions are: 10x10, 6x8, 9x8 (it does not need to be square).

POST https://atlas.microsoft.com/route/matrix/sync/json?api-version=1.0&subscription-key={subscription-key}

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 redirect URL in the Location field of the response header. This URL should be checked periodically until the response data or error information is available. If waitForResults parameter in the request is set to true, user will get a 200 response if the request is finished under 120 seconds.

The maximum size of a matrix for this API is 700 (the number of origins multiplied by the number of destinations). With that constraint in mind, examples of possible matrix dimensions are: 50x10, 10x10, 28x25. 10x70 (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/json?api-version=1.0&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 Location header in the response contains the URL to download the results of the request. This status URI looks like the following:

  GET https://atlas.microsoft.com/route/matrix/{matrixId}?api-version=1.0?subscription-key={subscription-key}

4. Client issues a GET request on the download URL obtained in Step 3 to download the results

Download Sync Results

When you make a POST request for Route Matrix Sync API, the service returns 200 response code for successful request and a response array. The response body will contain the data and there will be no possibility to retrieve the results later.

Download Async Results

When a request issues a 202 Accepted response, the request is being processed using our async pipeline. You will be given a URL to check the progress of your async request in the location header of the response. This status URI looks like the following:

  GET https://atlas.microsoft.com/route/matrix/{matrixId}?api-version=1.0?subscription-key={subscription-key}

The URL provided by the location header will return the following responses when a GET request is issued.

HTTP 202 Accepted - Matrix request was accepted but is still being processed. Please try again in some time.

HTTP 200 OK - Matrix request successfully processed. The response body contains all of the results.