Calculate a route - Amazon Location Service

Calculate a route

After you create a route calculator resource, you can submit an API request to calculate a route.

Use this route calculator resource to calculate routes between an origin, a destination and up to 23 waypoints for different modes of transportation, avoidances, and traffic conditions.

Start calculating routes

Submit a simple request by using the CalculateRoute operation. A simple request contains the following required fields:

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.

  • DeparturePosition – The starting position for which to calculate the route from. Defined as [longitude, latitude]

  • DestinationPosition – The end position to which to calculate the route. Defined as [longitude, latitude].

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

API

The following example is a CalculateRoute request using the route calculator resource ExampleCalculator. The request specifies calculating a route from a departure position [-122.7565, 49.0021] to a destination position [-122.3394, 47.6159].

POST /routes/v0/calculators/ExampleCalculator/calculate/route Content-type: application/json { "DeparturePosition": [-122.7565,49.0021], "DestinationPosition": [-122.3394, 47.6159] }
AWS CLI

The following example is a calculate-route command using the route calculator resource ExampleCalculator. The request specifies calculating a route from a departure position [-122.7565, 49.0021] to a destination position [-122.3394, 47.6159].

aws location \ calculate-route \ --calculator-name ExampleCalculator \ --departure-position -122.7565 49.0021 \ --destination-position -122.3394 47.6159

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 Content-type: application/json { "DeparturePosition": [-122.7565,49.0021], "DestinationPosition": [-122.3394, 47.6159], "DistanceUnit": "Miles" }

Waypoints

When calculating a route, you can specify up to 23 intermediate stopover points between the departure position and the destination position using waypoint positions.

  • WaypointPositions – Specifies an ordered list of intermediate positions to include along a route between the departure position and destination position.

    Note

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

The following CalculateRoute request calculates a route with 2 waypoints:

  • The departure position is [-122.7565, 49.0021], and the destination position is [-122.3394, 47.6159].

  • For the request parameter WaypointPositions:

    • The first stop over position is [-122.1884, 48.0936].

    • The second stop over position is [-122.3493, 47.6205].

  • To include the leg linestring geometry between these two waypoints, set the following optional parameter to true:

    • IncludeLegGeometry – Includes the geometry of each path between a pair of positions in the response.

POST /routes/v0/calculators/ExampleCalculator/calculate/route Content-type: application/json { "DeparturePosition": [-122.7565,49.0021], "DestinationPosition": [-122.3394, 47.6159], "WaypointPositions":[ [-122.1884,48.0936], [-122.3493,47.6205] ], "IncludeLegGeometry": true }

Positions not located on a road

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

The following CalculateRoute request specifies a departure position and destination position that's not located on a road:

POST /routes/v0/calculators/ExampleCalculator/calculate/route Content-type: application/json { "DeparturePosition": [-123.128014, 49.298472], "DestinationPosition": [-123.134701, 49. 294315] }

The resulting response returns a position that's snapped to a nearby road:

{ "Legs": [ { "StartPosition": [-123.12815, 49.29717], "EndPosition": [-123.13375, 49.2926], "Distance": 4.223, "DurationSeconds": 697, "Steps": [ { "StartPosition": [ -123.12815, 49.29717 ], "EndPosition": [ -123.12806, 49.29707 ], "Distance": 0.013, "DurationSeconds": 8 }, { "StartPosition": [ -123.12806, 49.29707 ], "EndPosition": [ -123.1288, 49.29659 ], "Distance": 0.082, "DurationSeconds": 36 }, { "StartPosition": [ -123.1288, 49.29659 ], "EndPosition": [ -123.12021, 49.29853 ], "Distance": 0.742, "DurationSeconds": 128 }, { "StartPosition": [ -123.12021, 49.29853 ], "EndPosition": [ -123.1201, 49.29959 ], "Distance": 0.131, "DurationSeconds": 26 }, { "StartPosition": [ -123.1201, 49.29959 ], "EndPosition": [ -123.13562, 49.30681 ], "Distance": 1.47, "DurationSeconds": 238 }, { "StartPosition": [ -123.13562, 49.30681 ], "EndPosition": [ -123.13693, 49.30615 ], "Distance": 0.121, "DurationSeconds": 28 }, { "StartPosition": [ -123.13693, 49.30615 ], "EndPosition": [ -123.13598, 49.29755 ], "Distance": 0.97, "DurationSeconds": 156 }, { "StartPosition": [ -123.13598, 49.29755 ], "EndPosition": [ -123.13688, 49.29717 ], "Distance": 0.085, "DurationSeconds": 15 }, { "StartPosition": [ -123.13688, 49.29717 ], "EndPosition": [ -123.13375, 49.2926 ], "Distance": 0.609, "DurationSeconds": 62 } ] } ], "Summary": { "RouteBBox": [ -123.13693, 49.2926, -123.1201, 49.30681 ], "DataSource": "Here", "Distance": 4.223, "DurationSeconds": 697, "DistanceUnit": "Kilometers" } }

Departure time

By default, if you don't provide a departure time in the request, the calculated route reflects optimal traffic conditions.

You can set a specific a departure time to use live and predictive traffic conditions from your chosen data provider, by using the following options:

  • DepartNow – When set to true, it uses live traffic conditions to calculate the fastest travel path.

  • DepartureTime – When provided, it uses predictive and known traffic conditions for the requested time. This field doesn’t accept a departure time in the past. Defined in the following format: YYYY-MM-DDThh:mm:ss.sssZ.

The following CalculateRoute request sets the departure time to July 2, 2024, at 12:15:20 UTC.

POST /routes/v0/calculators/ExampleCalculator/calculate/route Content-type: application/json { "DeparturePosition": [-122.7565,49.0021], "DestinationPosition": [-122.3394, 47.6159], "WaypointPositions":[ [-122.1884,48.0936], [-122.3493,47.6205] ] "IncludeLegGeometry": true, "DepartureTime": 2024-07-02T12:15:20.000Z, }

Travel mode

The mode of travel affects speed of travel and road compatibility. While the default mode of travel is by car, you can specify which mode of travel you're using while traveling along a route with the following optional parameter:

  • TravelMode – Specifies the mode of transport when calculating a route, such as: Car, Truck, or Walking.

If you specify a TravelMode of Car, you can specify additional route preferences with the following optional parameter:

  • CarModeOptions – Specifies route preferences when traveling in a car, such as AvoidFerries or AvoidTolls.

If you specify a TravelMode of Truck, you can specify additional route preferences with the following optional parameter:

  • TruckModeOptions – Specifies route preferences when traveling in a truck, such as AvoidFerries or AvoidTolls, in addition to specifying routes that can accommodate the TruckDimensions and TruckWeight.

The following CalculateRoute request specifies Truck as the mode of travel. Additional route restrictions include: avoiding routes that use ferries and avoiding roads that can't accommodate the truck dimensions and weight.

{ "DeparturePosition": [-122.7565,49.0021], "DestinationPosition": [-122.3394, 47.6159], "DepartNow": true, "TravelMode": "Truck", "TruckModeOptions": { "AvoidFerries": true, "AvoidTolls": false, "Dimensions": { "Height": 4.5, "Length": 15.5, "Unit": "Meters", "Width": 4.5 }, "Weight": { "Total": 7500, "Unit": "Pounds" } } }

Example response

The following is an example response when calling the CalculateRoute operation from the Amazon Location Routes API with the IncludeLegGeometry set to true, which includes the linestring geometry of each path between a pair of positions in the response.

Example request
POST /routes/v0/calculators/ExampleCalculator/calculate/route Content-type: application/json { "DeparturePosition": [-122.7565,49.0021], "DestinationPosition": [-122.3394, 47.6159], "IncludeLegGeometry": true }
Example response
{ "Legs": [ { "Distance": 178.5, "DurationSeconds": 6480, "EndPosition": [-122.3394,47.6159], "Geometry": { "LineString": [ [-122.7565,49.0021], [-122.3394,47.6159] ] }, "StartPosition": [-122.7565,49.0021], "Steps": [ { "Distance": 178.5, "DurationSeconds": 6480, "EndPosition": [-122.3394,47.6159], "GeometryOffset": 0, "StartPosition": [-122.7565,49.0021] } ] } ], "Summary": { "DataSource": "Esri", "Distance": 178.5, "DistanceUnit": "Kilometers", "DurationSeconds": 6480, "RouteBBox": [ -122.7565,49.0021, -122.3394,47.6159 ] } }