Calculate a route with Amazon Location - Amazon Location Service
Start calculating routesWaypointsExample response

Calculate a route with Amazon Location

You can use Amazon Location Service to calculate routes between an origin and a destination, with up to 23 waypoints along the route, for different modes of transportation, avoidances, and traffic conditions.

Note

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

Start calculating routes

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

  • 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].

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 waypoints, a departure time, and a travel mode in your request.

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"
}

Setting 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
}

Example response

The following is an example request with the corresponding 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
    ]
   }
}