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

# POST /route/matrix

`POST /route/matrix`

The `Route Matrix` 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 sync 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. For example, 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 the Route
Matrix API and use the travel cost to sort the drivers by their actual travel
distance or time from the restaurant.


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 sync request it's **2500** (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 2500, you might want to make synchronous
request. The maximum size of a matrix for this API is **2500** (the number of
origins multiplied by the number of destinations). With that constraint in
mind, examples of possible matrix dimensions are: 50x50, 60x40, 90x20 (it does
not need to be square).



### API Limitations
The synchronous processing of matrix is best suited for fast, small matrices
of route calculation. To calculate larger matrices and heavy route calculation,
use the asynchronous endpoint. The following limitation is applicable to the
synchronous 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

|------------------|------------------------|----------------------------|------------|
| 100              | 100         | 100              | N/A |
| 200              | 200         | 200              | 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.  |
| 2500             | 1000        | 1000             | - `departAt` or
`arriveAt` must be any.<br> - `traffic` must be historical.<br> - `travelMode`
must be either driving or truck<br> - No other parameters can be used
explicitly   |


Examples:
- Request of 10x20 matrix with `traffic=live`: This request will be processed
with a bounding box limit, as it matches a limit of up to 200, which includes
bounding box restrictions.

- Request of 10x20 matrix with default parameters (`traffic=historical`): This
request will be processed without a bounding box limit, as it matches a limit
of up to 2500, which does  not impose bounding box restrictions.

## Query parameters

- `api-version` string, required

## Headers

- `x-ms-client-id` string

## Response `200`

The request has succeeded.

- RouteMatrixResponse — This object is returned from a successful call.
  - `type` 'Feature', required — Specifies the `GeoJSON` type. The only supported object type is Feature. For more information, see [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946).
  - `geometry` object, nullable, required — The geometry object is null
  - `properties` RouteMatrixFeatureProperties, required — Route Matrix properties.
    - `summary` RouteMatrixSummary — Summary for the route matrix request
      - `successfulCount` integer — Number of successful routes within this matrix.
      - `totalCount` integer — Total number of routes within this matrix.
    - `matrix` RouteMatrixItemResult[] — The matrix of route results.
      - `statusCode` integer — The HTTP status code of the current cell.
      - `originIndex` integer — Index of the origin point
      - `destinationIndex` integer — Index of the destination point
      - `departureAt` string, date-time — The estimated departure time, which takes into account the traffic conditions, is formatted as a `dateTime` value defined by [RFC 3339, section 5.6](https://www.rfc-editor.org/rfc/rfc3339#section-5.6). It will reference the timezone offset by either `departAt` or `arrivalAt`. If not, then the UTC time will be used. If departAt or arriveAt is `any`, then departureAt is absent.
      - `arrivalAt` string, date-time — The estimated arrival time, which takes into account the traffic conditions, is formatted as a `dateTime` value defined by [RFC 3339, section 5.6](https://www.rfc-editor.org/rfc/rfc3339#section-5.6). It will reference the timezone offset by either `departAt` or `arrivalAt`. If not, then the UTC time will be used. If departAt or arriveAt is any, then departureAt is absent.
      - `distanceInMeters` number, double — Length In Meters property
      - `durationInSeconds` integer — Estimated travel time in seconds that does not include delays on the route due to traffic conditions.
      - `durationTrafficInSeconds` integer — The time that it takes, in seconds, to travel a corresponding `TravelDistance` with current traffic conditions. This value is provided if `traffic=live` is passed to account for current traffic conditions.
      - `error` CommonErrorDetail — The error detail.
        - `code` string — The error code.
        - `message` string — The error message.
        - `target` string — The error target.
        - `details` CommonErrorDetail[] — The error details.
        - `additionalInfo` ErrorAdditionalInfo[] — The error additional info.
          - `type` string — The additional info type.
          - `info` object — The additional info.

## 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)