RouteRequestRouteDirectionsBatch202Response interface

Route Directions Batch API

Applies to: see pricing tiers.

The Route Directions Batch API sends batches of queries to Route Directions API using just a single API call. 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.

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 14 days. The redirect URL returns a 404 response if used after the expiration period.

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

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

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 Note:- Please remember to add AUTH information (subscription-key/azure_auth - See Security) to the status URI before running it.
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."
                }
            }
        }
    ]
}