Calculating a route matrix Position restrictions Example response

Route planning with a route matrix

You can use Amazon Location Service to create inputs to your route planning and optimization software. You can create route results, including travel time and travel distance, for routes between a set of departure positions and a set of destination positions.

For example, given departure positions A and B, and destination positions X and Y, Amazon Location Service will return travel time and travel distance for routes from A to X, A to Y, B to X, and B to Y.

You can calculate the routes with different modes of transportation, avoidances, and traffic conditions. For example, you can specify that the vehicle is a truck that is 35 feet long, and the route calculated will use those restrictions to determine the travel time and travel distance.

The number of results returned (and routes calculated) is the number of departure positions multiplied by the number of destination positions. You are charged for each route calculated, not each request to the service, so a route matrix with 10 departures and 10 destinations will be billed as 100 routes.

Calculating a route matrix

You can calculate a matrix of routes between a set of departure positions and a set of destination positions. The route results will include travel time and travel distance.

Prerequisite

You must first create a route calculator resource and set up authentication for your requests to Amazon Location. For more information, see Prerequisites.

Submit a request by using the CalculateRouteMatrix operation. A minimal request contains the following required fields:

DeparturePositions – The set of starting positions for which to calculate the routes. Defined as an array of [longitude, latitude]
DestinationPositions – The set of end positions for which to calculate the routes. Defined as an array of [longitude, latitude].

Note

If you specify a departure or destination position that's not located on a road, Amazon Location moves the position to the nearest road.

You can optionally specify a departure time, and a travel mode in your request.

You can use the AWS CLI or the Amazon Location APIs.

By default, the response returns Distance in kilometers. You can change the unit of measurement to miles using the following optional parameter:

DistanceUnit – Specifies the unit system to use for the distance results.


POST /routes/v0/calculators/ExampleCalculator/calculate/route-matrix
Content-type: application/json
{
   "DeparturePositions": [
       [-122.7565,49.0021],
       [-122.2014,47.6101]
   ],
   "DestinationPositions": [
       [-122.3394, 47.6159],
       [-122.4813,48.7511]
   ],
   "DistanceUnit": "Miles"
}

Restrictions on departure and destination positions

When calculating a route matrix, there are restrictions on the departure and destination positions. These restrictions vary depending on the provider used by the RouteCalculator resource.

Limitation	Esri	Grab	HERE
Number of positions	Up to 10 departure positions and 10 destination positions.	Up to 350 departure positions and 350 destination positions.	Up to 350 departure positions and 350 destination positions. For longer routes, additional restrictions apply. See the section.
Distance between positions	Any pair of departure and destination positions must be within 400 km of each other (40km for walking routes).		All departure and destination positions must fall within a 180 km diameter circle. For longer routes, additional restrictions apply. See the section.
Route length	Routes will not be completed if the total travel time for the route is over 400 minutes.		Routes that deviate more than 10 km outside a circle around the departure and destination points will not be calculated. For longer routes, additional restrictions apply. See the section.
Regions	Calculating a route matrix is not supported in Korea.	Available in Southeast Asia. For a list of supported countries/regions and more information, see Countries/regions and area covered.	No additional restrictions.

Longer route planning

Calculating a matrix of route results is useful for efficient route planning, but the calculation can take some time. All of the Amazon Location Service data providers put limitations on the number of routes or the distance of the routes that can be calculated. For example, HERE allows creating routes between 350 departure and destination positions, but those positions must fall within a 180km circle. What if you want to plan with longer routes?

You can calculate a matrix of routes with unrestricted lengths for a smaller numbers of routes, using, a RouteCalculator with HERE as the data provider. This does not change the way that you call the CalculateRouteMatrix API, Amazon Location simply allows longer routes when you meet the requirements.

The requirements for longer length route calculations are:

The RouteCalculator must use the HERE data provider.
The number of departure positions must not be greater than 15.
The total number of routes to calculate must not be greater than 100.
Long distance routing is not allowed for truck routing with toll avoidances when the routes are greater than 1,000 km. This combination is slower to calculate, and can cause the call to time out. You can calculate these routes individually with the CalculateRoute operation.

If your call does not meet these requirements (for example, you are requesting 150 route calculations in a single call), then CalculateRouteMatrix will revert to only allowing the shorter route rules. You can then calculate the routes, as long as the positions are within a 180km circle.

When calculating longer routes, keep these points in mind:

Longer routes can take longer to calculate, even longer than the maximum time for Amazon Location APIs. If you get frequent timeouts with specific routes, you can try a smaller number of routes in each call to CalculateRouteMatrix.
If you add more destination or departure positions to your CalculateRouteMatrix request, the operation can switch into the more restricted mode, and you can get an error for a route that can be calculated without issue when there are fewer routes to create. In this case, reduce the number of destination or departure positions, and make multiple requests to get the full set of route calculations that you need.

Example response

The following is an example request with the corresponding response when calling the CalculateRouteMatrix operation from the Amazon Location Routes API.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Calculate route

Positions not located on a road