Route

Service:
Maps
API Version:
1.0

Operations

Get Route Directions

Applies to: S0 and S1 pricing tiers.

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 vehicle-specific Consumption Model. Please check Consumption Model for detailed explanation of the concepts and parameters involved.
Get Route Range

Route Range (Isochrone) API

Applies to: S1 pricing tier.

This service will calculate a set of locations that can be reached from the origin point based on fuel, energy, or time 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.
Post Route Directions

Applies to: S0 and S1 pricing tiers.

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.
Post Route Directions Batch Preview

Route Directions Batch API

Applies to: S1 pricing tier.

The Route Directions Batch API allows the caller to batch up to 700 Route Directions API queries/requests using just a single API call.

Submit 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 maximum number of queries that can be specified in the batch is 700 and the batch should contain at least 1 query.

Please note that the Route Directions Batch API 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.

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

Download Batch Results

To download the 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/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

When downloading the results of a 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. Also, 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:

  • RouteDirectionsResponse - 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."
                }
            }
        }
    ]
}

Data Retention Period

Please, be aware that batch results are available for download for 14 days, after which the request for results download will return 404 Not Found response.
Post Route Matrix Preview

Applies to: S1 pricing tier.

The Matrix Routing service allows calculation of a matrix of route summaries for a set of routes defined by origin and destination locations. For every given origin, this 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. For each route, the travel times and distances are calculated. You can use the computed costs to determine which routes to calculate using the Routing Directions API. If waitForResults parameter in the request is set to false (default value), this API 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 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 14 days. The redirect URL returns a 404 response if used after the expiration period.

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.

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.