--- title: "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." method: POST path: "/route/matrix/sync/{format}" --- # 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. `POST /route/matrix/sync/{format}` > [!NOTE] > > **Azure Maps Route v1 service retirement** > > The Azure Maps [Route v1](/rest/api/maps/route?view=rest-maps-1.0) 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](/rest/api/maps/route) service by 3/31/28. For more information, see [Migrate Azure Maps Route 1.0 APIs](/azure/azure-maps/migrate-route-v1-api). 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](/rest/api/maps/route/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. ## Query parameters - `api-version` string, required - `waitForResults` boolean - `computeTravelTimeFor` 'none' | 'all' - `sectionType` string[] - `arriveAt` string, date-time - `departAt` string, date-time - `vehicleAxleWeight` integer - `vehicleLength` number, double - `vehicleHeight` number, double - `vehicleWidth` number, double - `vehicleMaxSpeed` integer - `vehicleWeight` integer - `windingness` 'low' | 'normal' | 'high' - `hilliness` 'low' | 'normal' | 'high' - `travelMode` 'car' | 'truck' | 'taxi' | 'bus' | 'van' | 'motorcycle' | 'bicycle' | 'pedestrian' - `avoid` string[] - `traffic` boolean - `routeType` 'fastest' | 'shortest' | 'eco' | 'thrilling' - `vehicleLoadType` 'USHazmatClass1' | 'USHazmatClass2' | 'USHazmatClass3' | 'USHazmatClass4' | 'USHazmatClass5' | 'USHazmatClass6' | 'USHazmatClass7' | 'USHazmatClass8' | 'USHazmatClass9' | 'otherHazmatExplosive' | 'otherHazmatGeneral' | 'otherHazmatHarmfulToWater' ## Parameters - `../../../Common/preview/1.0/common.json#/components/parameters/ClientId` — unresolved $ref - `../../../Common/preview/1.0/common.json#/components/parameters/JsonFormat` — unresolved $ref ## Request body - RouteMatrixQuery — An object with a matrix of coordinates. - `origins` GeoJsonMultiPoint — unresolved $ref - `destinations` GeoJsonMultiPoint — unresolved $ref ## Response `200` Matrix request successfully processed. The response body contains all of the results. - RouteMatrixResult — This object is returned from a successful Route Matrix call. For ex, if 2 origins and 3 destinations are provided, there are going to 2 arrays with 3 elements in each. Each element's content depends on the options provided in the query. - `formatVersion` string — Format Version property - `matrix` array[] — Results as a 2 dimensional array of route summaries. - RouteMatrix[] - `statusCode` integer — StatusCode property for the current cell in the input matrix. - `response` RouteMatrixResultResponse — Response object of the current cell in the input matrix. - `routeSummary` RouteLegSummary — Summary object for route section. - `lengthInMeters` integer — Length In Meters property - `travelTimeInSeconds` integer — Estimated travel time in seconds property that includes the delay due to real-time traffic. Note that even when traffic=false travelTimeInSeconds still includes the delay due to traffic. If DepartAt is in the future, travel time is calculated using time-dependent historic traffic data. - `trafficDelayInSeconds` integer — Estimated delay in seconds caused by the real-time incident(s) according to traffic information. For routes planned with departure time in the future, delays is always 0. To return additional travel times using different types of traffic information, parameter computeTravelTimeFor=all needs to be added. - `departureTime` string, date-time — The estimated departure time for the route or leg. Time is in UTC. - `arrivalTime` string, date-time — The estimated arrival time for the route or leg. Time is in UTC. - `noTrafficTravelTimeInSeconds` integer — Estimated travel time calculated as if there are no delays on the route due to traffic conditions (e.g. congestion). Included only if computeTravelTimeFor = all is used in the query. - `historicTrafficTravelTimeInSeconds` integer — Estimated travel time calculated using time-dependent historic traffic data. Included only if computeTravelTimeFor = all is used in the query. - `liveTrafficIncidentsTravelTimeInSeconds` integer — Estimated travel time calculated using real-time speed data. Included only if computeTravelTimeFor = all is used in the query. - `fuelConsumptionInLiters` number, double — Estimated fuel consumption in liters using the Combustion Consumption Model. Included if vehicleEngineType is set to _combustion_ and constantSpeedConsumptionInLitersPerHundredkm is specified. The value will be non-negative. - `batteryConsumptionInkWh` number, double — Estimated electric energy consumption in kilowatt hours (kWh) using the Electric Consumption Model. Included if vehicleEngineType is set to electric and constantSpeedConsumptionInkWhPerHundredkm is specified. The value of batteryConsumptionInkWh includes the recuperated electric energy and can therefore be negative (which indicates gaining energy). If both maxChargeInkWh and currentChargeInkWh are specified, recuperation will be capped to ensure that the battery charge level never exceeds maxChargeInkWh. If neither maxChargeInkWh nor currentChargeInkWh are specified, unconstrained recuperation is assumed in the consumption calculation. - `summary` RouteMatrixSummary — Summary object - `successfulRoutes` integer — Number of successful routes in the response. - `totalRoutes` integer — Total number of routes requested. Number of cells in the input matrix. ## Other responses - `408` — Timeout: The request took longer to finish than the maximum amount of time defined in the api. - `default` — unresolved $ref ## Changes - **2026-07-13** (1.0) `03ff5298fed3` — 1 info - endpoint added [Change history](https://skmtc.dev/azure/apis/maps-route/changes/route/matrix/sync/:format/post.md) --- [API](https://skmtc.dev/azure/apis/maps-route.md) · [All operations](https://skmtc.dev/azure/apis/maps-route/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/azure/maps-route/revisions/03ff5298fed3/schema)