@azure-rest/maps-route package

This type represents the request body for the Batch service.

Batch request object

An item returned from Batch API. Extend with 'response' property.

This object is returned from a successful Batch service call. Extend with 'batchItems' property.

Summary of the results for the batch request

Effective parameter or data used when calling this Route API.

The error detail.

Common error response for all Azure Resource Manager APIs to return error details for failed operations. (This also follows the OData error response format.).

A valid GeoJSON Feature object type. Please refer to RFC 7946 for details.

A valid GeoJSON FeatureCollection object type. Please refer to RFC 7946 for details.

A valid GeoJSON GeometryCollection object type. Please refer to RFC 7946 for details.

A valid GeoJSON geometry object. The type must be one of the seven valid GeoJSON geometry types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon and GeometryCollection. Please refer to RFC 7946 for details.

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

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

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

Data contained by a GeoJson MultiPoint.

A valid GeoJSON MultiPolygon object type. Please refer to RFC 7946 for details.

A valid GeoJSON object. Please refer to RFC 7946 for details.

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

Data contained by a GeoJson Point.

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

A location represented as a latitude and longitude.

The optional parameters for the client

Post body parameters for Route directions.

An item returned from Route Directions Batch service call.

The result of the query. RouteDirections if the query completed successfully, ErrorResponse otherwise.

This object is returned from a successful Route Directions Batch service call.

This object is returned from a successful Route Directions call

The Get Route Directions API is an HTTP GET request that returns a route between an origin and a destination, passing through waypoints if specified. The route takes into account factors such as current traffic and the typical road speeds on the requested day of the week and time of day.

Information returned includes the distance, estimated travel time, and a representation of the route geometry. Additional routing information such as optimized waypoint order or turn by turn instructions is also available, depending on the options selected.

Routing service provides a set of parameters for a detailed description of a vehicle-specific consumption model. For more information, see Consumption Model.

The Get Route Directions Batch API is an HTTP GET request that sends batches of queries to the Get Route Directions API using a single request. You can call Get Route Directions Batch API to run either asynchronously (async) or synchronously (sync). The async API allows caller to batch up to 700 queries and sync API up to 100 queries.

Download Asynchronous Batch Results

To download the async batch results you will issue a GET request to the batch download endpoint. This download URL can be obtained from the Location header of a successful POST batch request and looks like the following:

https://atlas.microsoft.com/route/directions/batch/{batch-id}?api-version=1.0&subscription-key={subscription-key}

Here's the typical sequence of operations for downloading the batch results:

1. Client sends a GET request using the download URL.

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

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

   HTTP 200 OK - Batch request successfully processed. The response body contains all the batch results.

Batch Response Model

The returned data content is similar for async and sync requests. When downloading the results of an async batch request, if the batch has finished processing, the response body contains the batch response. This batch response contains a summary component that indicates the totalRequests that were part of the original batch request and successfulRequestsi.e. queries which were executed successfully. The batch response also includes a batchItems array which contains a response for each and every query in the batch request. The batchItems will contain the results in the exact same order the original queries were sent in the batch request. Each item in batchItems contains statusCode and response fields. Each response in batchItems is of one of the following types:

• RouteDirections - If the query completed successfully.

• Error - If the query failed. The response will contain a code and a message in this case.

Here's a sample Batch Response with 1 successful and 1 failed result:

{
    "summary": {
        "successfulRequests": 1,
        "totalRequests": 2
    },
    "batchItems": [
        {
            "statusCode": 200,
            "response": {
                "routes": [
                    {
                        "summary": {
                            "lengthInMeters": 1758,
                            "travelTimeInSeconds": 387,
                            "trafficDelayInSeconds": 0,
                            "departureTime": "2018-07-17T00:49:56+00:00",
                            "arrivalTime": "2018-07-17T00:56:22+00:00"
                        },
                        "legs": [
                            {
                                "summary": {
                                    "lengthInMeters": 1758,
                                    "travelTimeInSeconds": 387,
                                    "trafficDelayInSeconds": 0,
                                    "departureTime": "2018-07-17T00:49:56+00:00",
                                    "arrivalTime": "2018-07-17T00:56:22+00:00"
                                },
                                "points": [
                                    {
                                        "latitude": 47.62094,
                                        "longitude": -122.34892
                                    },
                                    {
                                        "latitude": 47.62094,
                                        "longitude": -122.3485
                                    },
                                    {
                                        "latitude": 47.62095,
                                        "longitude": -122.3476
                                    }
                                ]
                            }
                        ],
                        "sections": [
                            {
                                "startPointIndex": 0,
                                "endPointIndex": 40,
                                "sectionType": "TRAVEL_MODE",
                                "travelMode": "bicycle"
                            }
                        ]
                    }
                ]
            }
        },
        {
            "statusCode": 400,
            "response":
            {
                "error":
                {
                    "code": "400 BadRequest",
                    "message": "Bad request: one or more parameters were incorrectly specified or are mutually exclusive."
                }
            }
        }
    ]
}

The Get Route Directions Batch API is an HTTP GET request that sends batches of queries to the Get Route Directions API using a single request. You can call Get Route Directions Batch API to run either asynchronously (async) or synchronously (sync). The async API allows caller to batch up to 700 queries and sync API up to 100 queries.

Download Asynchronous Batch Results

To download the async batch results you will issue a GET request to the batch download endpoint. This download URL can be obtained from the Location header of a successful POST batch request and looks like the following:

https://atlas.microsoft.com/route/directions/batch/{batch-id}?api-version=1.0&subscription-key={subscription-key}

Here's the typical sequence of operations for downloading the batch results:

1. Client sends a GET request using the download URL.

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

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

   HTTP 200 OK - Batch request successfully processed. The response body contains all the batch results.

Batch Response Model

The returned data content is similar for async and sync requests. When downloading the results of an async batch request, if the batch has finished processing, the response body contains the batch response. This batch response contains a summary component that indicates the totalRequests that were part of the original batch request and successfulRequestsi.e. queries which were executed successfully. The batch response also includes a batchItems array which contains a response for each and every query in the batch request. The batchItems will contain the results in the exact same order the original queries were sent in the batch request. Each item in batchItems contains statusCode and response fields. Each response in batchItems is of one of the following types:

• RouteDirections - If the query completed successfully.

• Error - If the query failed. The response will contain a code and a message in this case.

Here's a sample Batch Response with 1 successful and 1 failed result:

{
    "summary": {
        "successfulRequests": 1,
        "totalRequests": 2
    },
    "batchItems": [
        {
            "statusCode": 200,
            "response": {
                "routes": [
                    {
                        "summary": {
                            "lengthInMeters": 1758,
                            "travelTimeInSeconds": 387,
                            "trafficDelayInSeconds": 0,
                            "departureTime": "2018-07-17T00:49:56+00:00",
                            "arrivalTime": "2018-07-17T00:56:22+00:00"
                        },
                        "legs": [
                            {
                                "summary": {
                                    "lengthInMeters": 1758,
                                    "travelTimeInSeconds": 387,
                                    "trafficDelayInSeconds": 0,
                                    "departureTime": "2018-07-17T00:49:56+00:00",
                                    "arrivalTime": "2018-07-17T00:56:22+00:00"
                                },
                                "points": [
                                    {
                                        "latitude": 47.62094,
                                        "longitude": -122.34892
                                    },
                                    {
                                        "latitude": 47.62094,
                                        "longitude": -122.3485
                                    },
                                    {
                                        "latitude": 47.62095,
                                        "longitude": -122.3476
                                    }
                                ]
                            }
                        ],
                        "sections": [
                            {
                                "startPointIndex": 0,
                                "endPointIndex": 40,
                                "sectionType": "TRAVEL_MODE",
                                "travelMode": "bicycle"
                            }
                        ]
                    }
                ]
            }
        },
        {
            "statusCode": 400,
            "response":
            {
                "error":
                {
                    "code": "400 BadRequest",
                    "message": "Bad request: one or more parameters were incorrectly specified or are mutually exclusive."
                }
            }
        }
    ]
}

The Get Route Directions API is an HTTP GET request that returns a route between an origin and a destination, passing through waypoints if specified. The route takes into account factors such as current traffic and the typical road speeds on the requested day of the week and time of day.

Information returned includes the distance, estimated travel time, and a representation of the route geometry. Additional routing information such as optimized waypoint order or turn by turn instructions is also available, depending on the options selected.

Routing service provides a set of parameters for a detailed description of a vehicle-specific consumption model. For more information, see Consumption Model.

The Post Route Directions API is an HTTP POST request that returns a route between an origin and a destination, passing through waypoints if they are specified. The route will take into account factors such as current traffic and the typical road speeds on the requested day of the week and time of day.

Information returned includes the distance, estimated travel time, and a representation of the route geometry. Additional routing information such as optimized waypoint order or turn by turn instructions is also available, depending on the options selected.

Routing service provides a set of parameters for a detailed description of a vehicle-specific Consumption Model. Please check Consumption Model for detailed explanation of the concepts and parameters involved.

The Post Route Directions API is an HTTP POST request that returns a route between an origin and a destination, passing through waypoints if they are specified. The route will take into account factors such as current traffic and the typical road speeds on the requested day of the week and time of day.

Information returned includes the distance, estimated travel time, and a representation of the route geometry. Additional routing information such as optimized waypoint order or turn by turn instructions is also available, depending on the options selected.

Routing service provides a set of parameters for a detailed description of a vehicle-specific Consumption Model. Please check Consumption Model for detailed explanation of the concepts and parameters involved.

The Get Route Matrix API is an HTTP GET request that computes the travel time and distance for all possible pairs in a list of origins and destinations. Unlike the Get Route Directions API, which provide detailed route instructions, this API focuses on efficiency by giving you the cost (travel time and distance) of routing from each origin to every destination. For more information, see Best practices for Azure Maps Route service.

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

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

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

The Get Route Matrix API is an HTTP GET request that computes the travel time and distance for all possible pairs in a list of origins and destinations. Unlike the Get Route Directions API, which provide detailed route instructions, this API focuses on efficiency by giving you the cost (travel time and distance) of routing from each origin to every destination. For more information, see Best practices for Azure Maps Route service.

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

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

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

The Get Route Range (Isochrone) API is an HTTP GET request that will calculate a set of locations that can be reached from the origin point based on fuel, energy, time or distance budget that is specified. A polygon boundary (or Isochrone) is returned in a counterclockwise orientation as well as the precise polygon center which was the result of the origin point.

The returned polygon can be used for further processing such as Search Inside Geometry to search for POIs within the provided isochrone.

The Get Route Range (Isochrone) API is an HTTP GET request that will calculate a set of locations that can be reached from the origin point based on fuel, energy, time or distance budget that is specified. A polygon boundary (or Isochrone) is returned in a counterclockwise orientation as well as the precise polygon center which was the result of the origin point.

The returned polygon can be used for further processing such as Search Inside Geometry to search for POIs within the provided isochrone.

Contains guidance related elements. This field is present only when guidance was requested and is available.

Groups a sequence of instruction elements which are related to each other. The sequence range is constrained with firstInstructionIndex and lastInstructionIndex. When human-readable text messages are requested for guidance (instructionType=text or tagged), then the instructionGroup has a summary message returned when available.

A set of attributes describing a maneuver, e.g. 'Turn right', 'Keep left', 'Take the ferry', 'Take the motorway', 'Arrive'.

A description of a part of a route, comprised of a list of points. Each additional waypoint provided in the request will result in an additional leg in the returned route.

Matrix result object

An object with a matrix of coordinates.

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.

Response object of the current cell in the input matrix.

Summary object

Optimized way point object.

Reachable Range

This object is returned from a successful Route Reachable Range call

Reports the effective settings used in the current call.

The Post Route Directions Batch API is an HTTP POST request that sends batches of queries to the Get Route Directions API using a single asynchronous request. You can call Route Directions Batch API to run either asynchronously (async) or synchronously (sync). The async API allows caller to batch up to 700 queries and sync API up to 100 queries. To call the Post Route Directions Batch API in a synchronous request, see Post Route Directions Batch Sync.

Submit Asynchronous Batch Request

The Asynchronous API is appropriate for processing big volumes of relatively complex route requests

• It allows the retrieval of results in a separate call (multiple downloads are possible).
• The asynchronous API is optimized for reliability and is not expected to run into a timeout.
• The number of batch items is limited to 700 for this API.

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. The asynchronous responses are stored for 24 hours. The redirect URL returns a 404 response if used after the expiration period.

Please note that asynchronous batch request is a long-running operation. Here's a typical sequence of operations:

1. Client sends a Route Directions Batch POST request to Azure Maps.

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

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

   HTTP 202 Accepted - Batch request has been accepted.

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

3. If the batch request was accepted successfully, the Location header in the response contains the URL to download the results of the batch request. This status URI looks like following:

GET https://atlas.microsoft.com/route/directions/batch/{batch-id}?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 batch results.

POST Body for Batch Request

To send the route directions queries you will use a POST request where the request body will contain the batchItems array in json format and the Content-Type header will be set to application/json. Here's a sample request body containing 3 route directions queries:

{
    "batchItems": [
        { "query": "?query=47.620659,-122.348934:47.610101,-122.342015&travelMode=bicycle&routeType=eco&traffic=false" },
        { "query": "?query=40.759856,-73.985108:40.771136,-73.973506&travelMode=pedestrian&routeType=shortest" },
        { "query": "?query=48.923159,-122.557362:32.621279,-116.840362" }
    ]
}

A route directions query in a batch is just a partial URL without the protocol, base URL, path, api-version and subscription-key. It can accept any of the supported route directions URI parameters. The string values in the route directions query must be properly escaped (e.g. " character should be escaped with \ ) and it should also be properly URL-encoded.

The async API allows caller to batch up to 700 queries and sync API up to 100 queries, and the batch should contain at least 1 query.

Download Asynchronous Batch Results

To download the async batch results you will issue a GET request to the batch download endpoint. This download URL can be obtained from the Location header of a successful POST batch request and looks like the following:

https://atlas.microsoft.com/route/directions/batch/{batch-id}?api-version=1.0&subscription-key={subscription-key}

Here's the typical sequence of operations for downloading the batch results:

1. Client sends a GET request using the download URL.

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

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

   HTTP 200 OK - Batch request successfully processed. The response body contains all the batch results.

Batch Response Model

The returned data content is similar for async and sync requests. When downloading the results of an async batch request, if the batch has finished processing, the response body contains the batch response. This batch response contains a summary component that indicates the totalRequests that were part of the original batch request and successfulRequestsi.e. queries which were executed successfully. The batch response also includes a batchItems array which contains a response for each and every query in the batch request. The batchItems will contain the results in the exact same order the original queries were sent in the batch request. Each item in batchItems contains statusCode and response fields. Each response in batchItems is of one of the following types:

• RouteDirections - If the query completed successfully.

• Error - If the query failed. The response will contain a code and a message in this case.

Here's a sample Batch Response with 1 successful and 1 failed result:

{
    "summary": {
        "successfulRequests": 1,
        "totalRequests": 2
    },
    "batchItems": [
        {
            "statusCode": 200,
            "response": {
                "routes": [
                    {
                        "summary": {
                            "lengthInMeters": 1758,
                            "travelTimeInSeconds": 387,
                            "trafficDelayInSeconds": 0,
                            "departureTime": "2018-07-17T00:49:56+00:00",
                            "arrivalTime": "2018-07-17T00:56:22+00:00"
                        },
                        "legs": [
                            {
                                "summary": {
                                    "lengthInMeters": 1758,
                                    "travelTimeInSeconds": 387,
                                    "trafficDelayInSeconds": 0,
                                    "departureTime": "2018-07-17T00:49:56+00:00",
                                    "arrivalTime": "2018-07-17T00:56:22+00:00"
                                },
                                "points": [
                                    {
                                        "latitude": 47.62094,
                                        "longitude": -122.34892
                                    },
                                    {
                                        "latitude": 47.62094,
                                        "longitude": -122.3485
                                    },
                                    {
                                        "latitude": 47.62095,
                                        "longitude": -122.3476
                                    }
                                ]
                            }
                        ],
                        "sections": [
                            {
                                "startPointIndex": 0,
                                "endPointIndex": 40,
                                "sectionType": "TRAVEL_MODE",
                                "travelMode": "bicycle"
                            }
                        ]
                    }
                ]
            }
        },
        {
            "statusCode": 400,
            "response":
            {
                "error":
                {
                    "code": "400 BadRequest",
                    "message": "Bad request: one or more parameters were incorrectly specified or are mutually exclusive."
                }
            }
        }
    ]
}

The Post Route Directions Batch API is an HTTP POST request that sends batches of queries to the Get Route Directions API using a single asynchronous request. You can call Route Directions Batch API to run either asynchronously (async) or synchronously (sync). The async API allows caller to batch up to 700 queries and sync API up to 100 queries. To call the Post Route Directions Batch API in a synchronous request, see Post Route Directions Batch Sync.

Submit Asynchronous Batch Request

The Asynchronous API is appropriate for processing big volumes of relatively complex route requests

• It allows the retrieval of results in a separate call (multiple downloads are possible).
• The asynchronous API is optimized for reliability and is not expected to run into a timeout.
• The number of batch items is limited to 700 for this API.

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. The asynchronous responses are stored for 24 hours. The redirect URL returns a 404 response if used after the expiration period.

Please note that asynchronous batch request is a long-running operation. Here's a typical sequence of operations:

1. Client sends a Route Directions Batch POST request to Azure Maps.

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

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

   HTTP 202 Accepted - Batch request has been accepted.

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

3. If the batch request was accepted successfully, the Location header in the response contains the URL to download the results of the batch request. This status URI looks like following:

GET https://atlas.microsoft.com/route/directions/batch/{batch-id}?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 batch results.

POST Body for Batch Request

To send the route directions queries you will use a POST request where the request body will contain the batchItems array in json format and the Content-Type header will be set to application/json. Here's a sample request body containing 3 route directions queries:

{
    "batchItems": [
        { "query": "?query=47.620659,-122.348934:47.610101,-122.342015&travelMode=bicycle&routeType=eco&traffic=false" },
        { "query": "?query=40.759856,-73.985108:40.771136,-73.973506&travelMode=pedestrian&routeType=shortest" },
        { "query": "?query=48.923159,-122.557362:32.621279,-116.840362" }
    ]
}

A route directions query in a batch is just a partial URL without the protocol, base URL, path, api-version and subscription-key. It can accept any of the supported route directions URI parameters. The string values in the route directions query must be properly escaped (e.g. " character should be escaped with \ ) and it should also be properly URL-encoded.

The async API allows caller to batch up to 700 queries and sync API up to 100 queries, and the batch should contain at least 1 query.

Download Asynchronous Batch Results

To download the async batch results you will issue a GET request to the batch download endpoint. This download URL can be obtained from the Location header of a successful POST batch request and looks like the following:

https://atlas.microsoft.com/route/directions/batch/{batch-id}?api-version=1.0&subscription-key={subscription-key}

Here's the typical sequence of operations for downloading the batch results:

1. Client sends a GET request using the download URL.

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

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

   HTTP 200 OK - Batch request successfully processed. The response body contains all the batch results.

Batch Response Model

The returned data content is similar for async and sync requests. When downloading the results of an async batch request, if the batch has finished processing, the response body contains the batch response. This batch response contains a summary component that indicates the totalRequests that were part of the original batch request and successfulRequestsi.e. queries which were executed successfully. The batch response also includes a batchItems array which contains a response for each and every query in the batch request. The batchItems will contain the results in the exact same order the original queries were sent in the batch request. Each item in batchItems contains statusCode and response fields. Each response in batchItems is of one of the following types:

• RouteDirections - If the query completed successfully.

• Error - If the query failed. The response will contain a code and a message in this case.

Here's a sample Batch Response with 1 successful and 1 failed result:

{
    "summary": {
        "successfulRequests": 1,
        "totalRequests": 2
    },
    "batchItems": [
        {
            "statusCode": 200,
            "response": {
                "routes": [
                    {
                        "summary": {
                            "lengthInMeters": 1758,
                            "travelTimeInSeconds": 387,
                            "trafficDelayInSeconds": 0,
                            "departureTime": "2018-07-17T00:49:56+00:00",
                            "arrivalTime": "2018-07-17T00:56:22+00:00"
                        },
                        "legs": [
                            {
                                "summary": {
                                    "lengthInMeters": 1758,
                                    "travelTimeInSeconds": 387,
                                    "trafficDelayInSeconds": 0,
                                    "departureTime": "2018-07-17T00:49:56+00:00",
                                    "arrivalTime": "2018-07-17T00:56:22+00:00"
                                },
                                "points": [
                                    {
                                        "latitude": 47.62094,
                                        "longitude": -122.34892
                                    },
                                    {
                                        "latitude": 47.62094,
                                        "longitude": -122.3485
                                    },
                                    {
                                        "latitude": 47.62095,
                                        "longitude": -122.3476
                                    }
                                ]
                            }
                        ],
                        "sections": [
                            {
                                "startPointIndex": 0,
                                "endPointIndex": 40,
                                "sectionType": "TRAVEL_MODE",
                                "travelMode": "bicycle"
                            }
                        ]
                    }
                ]
            }
        },
        {
            "statusCode": 400,
            "response":
            {
                "error":
                {
                    "code": "400 BadRequest",
                    "message": "Bad request: one or more parameters were incorrectly specified or are mutually exclusive."
                }
            }
        }
    ]
}

The Post Route Directions Batch Sync API is an HTTP POST request that sends batches of queries to the Get Route Directions API using a single synchronous request. You can call Route Directions Batch API to run either asynchronously (async) or synchronously (sync). The async API allows caller to batch up to 700 queries and sync API up to 100 queries. To call the Post Route Directions Batch API in a asynchronous request, see Post Route Directions Batch.

Submit Synchronous Batch Request

The Synchronous API is recommended for lightweight batch requests. When the service receives a request, it will respond as soon as the batch items are calculated and there will be no possibility to retrieve the results later. The Synchronous API will return a timeout error (a 408 response) if the request takes longer than 60 seconds. The number of batch items is limited to 100 for this API.

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

Batch Response Model

The returned data content is similar for async and sync requests. When downloading the results of an async batch request, if the batch has finished processing, the response body contains the batch response. This batch response contains a summary component that indicates the totalRequests that were part of the original batch request and successfulRequestsi.e. queries which were executed successfully. The batch response also includes a batchItems array which contains a response for each and every query in the batch request. The batchItems will contain the results in the exact same order the original queries were sent in the batch request. Each item in batchItems contains statusCode and response fields. Each response in batchItems is of one of the following types:

• RouteDirections - If the query completed successfully.

• Error - If the query failed. The response will contain a code and a message in this case.

Here's a sample Batch Response with 1 successful and 1 failed result:

{
    "summary": {
        "successfulRequests": 1,
        "totalRequests": 2
    },
    "batchItems": [
        {
            "statusCode": 200,
            "response": {
                "routes": [
                    {
                        "summary": {
                            "lengthInMeters": 1758,
                            "travelTimeInSeconds": 387,
                            "trafficDelayInSeconds": 0,
                            "departureTime": "2018-07-17T00:49:56+00:00",
                            "arrivalTime": "2018-07-17T00:56:22+00:00"
                        },
                        "legs": [
                            {
                                "summary": {
                                    "lengthInMeters": 1758,
                                    "travelTimeInSeconds": 387,
                                    "trafficDelayInSeconds": 0,
                                    "departureTime": "2018-07-17T00:49:56+00:00",
                                    "arrivalTime": "2018-07-17T00:56:22+00:00"
                                },
                                "points": [
                                    {
                                        "latitude": 47.62094,
                                        "longitude": -122.34892
                                    },
                                    {
                                        "latitude": 47.62094,
                                        "longitude": -122.3485
                                    },
                                    {
                                        "latitude": 47.62095,
                                        "longitude": -122.3476
                                    }
                                ]
                            }
                        ],
                        "sections": [
                            {
                                "startPointIndex": 0,
                                "endPointIndex": 40,
                                "sectionType": "TRAVEL_MODE",
                                "travelMode": "bicycle"
                            }
                        ]
                    }
                ]
            }
        },
        {
            "statusCode": 400,
            "response":
            {
                "error":
                {
                    "code": "400 BadRequest",
                    "message": "Bad request: one or more parameters were incorrectly specified or are mutually exclusive."
                }
            }
        }
    ]
}

The Post Route Directions Batch Sync API is an HTTP POST request that sends batches of queries to the Get Route Directions API using a single synchronous request. You can call Route Directions Batch API to run either asynchronously (async) or synchronously (sync). The async API allows caller to batch up to 700 queries and sync API up to 100 queries. To call the Post Route Directions Batch API in a asynchronous request, see Post Route Directions Batch.

Submit Synchronous Batch Request

The Synchronous API is recommended for lightweight batch requests. When the service receives a request, it will respond as soon as the batch items are calculated and there will be no possibility to retrieve the results later. The Synchronous API will return a timeout error (a 408 response) if the request takes longer than 60 seconds. The number of batch items is limited to 100 for this API.

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

Batch Response Model

The returned data content is similar for async and sync requests. When downloading the results of an async batch request, if the batch has finished processing, the response body contains the batch response. This batch response contains a summary component that indicates the totalRequests that were part of the original batch request and successfulRequestsi.e. queries which were executed successfully. The batch response also includes a batchItems array which contains a response for each and every query in the batch request. The batchItems will contain the results in the exact same order the original queries were sent in the batch request. Each item in batchItems contains statusCode and response fields. Each response in batchItems is of one of the following types:

• RouteDirections - If the query completed successfully.

• Error - If the query failed. The response will contain a code and a message in this case.

Here's a sample Batch Response with 1 successful and 1 failed result:

{
    "summary": {
        "successfulRequests": 1,
        "totalRequests": 2
    },
    "batchItems": [
        {
            "statusCode": 200,
            "response": {
                "routes": [
                    {
                        "summary": {
                            "lengthInMeters": 1758,
                            "travelTimeInSeconds": 387,
                            "trafficDelayInSeconds": 0,
                            "departureTime": "2018-07-17T00:49:56+00:00",
                            "arrivalTime": "2018-07-17T00:56:22+00:00"
                        },
                        "legs": [
                            {
                                "summary": {
                                    "lengthInMeters": 1758,
                                    "travelTimeInSeconds": 387,
                                    "trafficDelayInSeconds": 0,
                                    "departureTime": "2018-07-17T00:49:56+00:00",
                                    "arrivalTime": "2018-07-17T00:56:22+00:00"
                                },
                                "points": [
                                    {
                                        "latitude": 47.62094,
                                        "longitude": -122.34892
                                    },
                                    {
                                        "latitude": 47.62094,
                                        "longitude": -122.3485
                                    },
                                    {
                                        "latitude": 47.62095,
                                        "longitude": -122.3476
                                    }
                                ]
                            }
                        ],
                        "sections": [
                            {
                                "startPointIndex": 0,
                                "endPointIndex": 40,
                                "sectionType": "TRAVEL_MODE",
                                "travelMode": "bicycle"
                            }
                        ]
                    }
                ]
            }
        },
        {
            "statusCode": 400,
            "response":
            {
                "error":
                {
                    "code": "400 BadRequest",
                    "message": "Bad request: one or more parameters were incorrectly specified or are mutually exclusive."
                }
            }
        }
    ]
}

The Post Route Directions Batch Sync API is an HTTP POST request that sends batches of queries to the Get Route Directions API using a single synchronous request. You can call Route Directions Batch API to run either asynchronously (async) or synchronously (sync). The async API allows caller to batch up to 700 queries and sync API up to 100 queries. To call the Post Route Directions Batch API in a asynchronous request, see Post Route Directions Batch.

Submit Synchronous Batch Request

The Synchronous API is recommended for lightweight batch requests. When the service receives a request, it will respond as soon as the batch items are calculated and there will be no possibility to retrieve the results later. The Synchronous API will return a timeout error (a 408 response) if the request takes longer than 60 seconds. The number of batch items is limited to 100 for this API.

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

Batch Response Model

The returned data content is similar for async and sync requests. When downloading the results of an async batch request, if the batch has finished processing, the response body contains the batch response. This batch response contains a summary component that indicates the totalRequests that were part of the original batch request and successfulRequestsi.e. queries which were executed successfully. The batch response also includes a batchItems array which contains a response for each and every query in the batch request. The batchItems will contain the results in the exact same order the original queries were sent in the batch request. Each item in batchItems contains statusCode and response fields. Each response in batchItems is of one of the following types:

• RouteDirections - If the query completed successfully.

• Error - If the query failed. The response will contain a code and a message in this case.

Here's a sample Batch Response with 1 successful and 1 failed result:

{
    "summary": {
        "successfulRequests": 1,
        "totalRequests": 2
    },
    "batchItems": [
        {
            "statusCode": 200,
            "response": {
                "routes": [
                    {
                        "summary": {
                            "lengthInMeters": 1758,
                            "travelTimeInSeconds": 387,
                            "trafficDelayInSeconds": 0,
                            "departureTime": "2018-07-17T00:49:56+00:00",
                            "arrivalTime": "2018-07-17T00:56:22+00:00"
                        },
                        "legs": [
                            {
                                "summary": {
                                    "lengthInMeters": 1758,
                                    "travelTimeInSeconds": 387,
                                    "trafficDelayInSeconds": 0,
                                    "departureTime": "2018-07-17T00:49:56+00:00",
                                    "arrivalTime": "2018-07-17T00:56:22+00:00"
                                },
                                "points": [
                                    {
                                        "latitude": 47.62094,
                                        "longitude": -122.34892
                                    },
                                    {
                                        "latitude": 47.62094,
                                        "longitude": -122.3485
                                    },
                                    {
                                        "latitude": 47.62095,
                                        "longitude": -122.3476
                                    }
                                ]
                            }
                        ],
                        "sections": [
                            {
                                "startPointIndex": 0,
                                "endPointIndex": 40,
                                "sectionType": "TRAVEL_MODE",
                                "travelMode": "bicycle"
                            }
                        ]
                    }
                ]
            }
        },
        {
            "statusCode": 400,
            "response":
            {
                "error":
                {
                    "code": "400 BadRequest",
                    "message": "Bad request: one or more parameters were incorrectly specified or are mutually exclusive."
                }
            }
        }
    ]
}

The Post 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 an asynchronous (async) request. To make a synchronous (sync) request, see Post Route Matrix Sync. 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.

The Post 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 an asynchronous (async) request. To make a synchronous (sync) request, see Post Route Matrix Sync. 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.

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.

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.

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.

Route sections contain additional information about parts of a route. Each section contains at least the elements startPointIndex, endPointIndex, and sectionType.

The cause of the traffic event. Can contain mainCauseCode and subCauseCode elements. Can be used to define iconography and descriptions.

Details of the traffic event, using definitions in the TPEG2-TEC standard. Can contain effectCode and causes elements.

Summary object

A simple poller that can be used to poll a long running operation.

A valid GeoJSON geometry object. The type must be one of the seven valid GeoJSON geometry types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon and GeometryCollection. Please refer to RFC 7946 for details.

A valid GeoJSON object. Please refer to RFC 7946 for details.

Create a batch request body of a bunch of route direction requests.

Creates an instance of MapsRouteClient from a subscription key.

Example

import MapsRoute from "@azure-rest/maps-route";
import { AzureKeyCredential } from "@azure/core-auth";

const credential = new AzureKeyCredential("<subscription-key>");
const client = MapsRoute(credential);

Creates an instance of MapsRoute from an Azure Identity TokenCredential.

Example

import MapsRoute from "@azure-rest/maps-route";
import { DefaultAzureCredential } from "@azure/identity";

const credential = new DefaultAzureCredential();
const client = MapsRoute(credential, "<maps-account-client-id>");

Creates an instance of MapsRoute from an Azure Identity AzureSASCredential.

Example

import MapsRoute from "@azure-rest/maps-route";
import { AzureSASCredential } from "@azure/core-auth";

const credential = new AzureSASCredential("<SAS Token>");
const client = MapsRoute(credential);

Helper function that builds a Poller object to help polling a long running operation.

Transform an array of [Latitude, Longtitute] to a string in the following format: "Latitude_1,Longtitute_1:Latitude_2,Longtitute_2:..."