# Calculate routes
<a name="calculate-routes"></a>

The Routes API calculates routes between two or more locations with or without avoidances for different travel modes such as car, truck, scooter, and pedestrian. With this API, you can customize routing options and request additional route-related information to meet specific needs. This API supports turn-by-turn navigation and customizes route calculations by applying parameters like avoiding toll roads, motorways, or ferries. The API also returns speed limits and toll costs.

For more information, see [CalculateRoutes](https://docs.aws.amazon.com/location/latest/APIReference/API_CalculateRoutes.html) in the *Amazon Location Service API Reference*.

For example requests, responses, cURL, and CLI commands for this API, see [How to use Calculate routes](https://docs.aws.amazon.com/location/latest/developerguide/calculate-routes-how-to.html).

![\[An overview of Amazon Location Service Routes.\]](http://docs.aws.amazon.com/location/latest/developerguide/images/routesV2/P2P-Turn-by-turn-navigation.gif)


## Use cases
<a name="use-cases"></a>
+ **Display geographic details on a route map:** Use advanced mapping features to visualize detailed routes with rich geographic information, including landmarks, terrain, and urban infrastructure. Enhance decision-making by allowing users to view clear routes from their starting point to their destination. This feature can support navigation, planning, and various logistics scenarios, and display routes for travel modes such as cars, trucks, scooters, and pedestrians. Customize routes by adding elements like avoidances or toll calculations.
+ **Show turn-by-turn navigation:** Provide seamless navigation support on web and mobile devices. Users can access turn-by-turn directions, ensuring efficient travel. Both platforms can leverage navigation instructions to offer routes for personal or business travel, including speed limits.
+ **Calculate toll costs along routes:** Incorporate toll cost calculations into route planning to provide accurate pricing estimates for routes that include toll roads, bridges, or tunnels. Display toll costs upfront to help drivers and planners make cost-effective decisions and avoid tolls when necessary.
+ **Ensure compliance with speed limits:** Integrate speed limit data to help drivers stay within legal limits, reducing the risk of fines and promoting safer, fuel-efficient driving. Logistics and fleet management can also benefit by monitoring speed compliance in real time.
+ **Assist with freight and vehicle routing solutions:** Simplify freight and vehicle routing operations by integrating routes, navigation, and tracking capabilities into logistics portals. Efficiently plan routes for multiple deliveries, track shipments in real-time, and manage fuel costs through better routing.

## Understand the request
<a name="understanding-request"></a>

**Note**  
 For customers in `ap-southeast-1` and `ap-southeast-5`, supported request and response fields may differ. Refer to the [CalculateRoutes API Reference](https://docs.aws.amazon.com/location/latest/APIReference/API_CalculateRoutes.html) for details. 

The request requires `Origin` and `Destination` parameters, while optional parameters like `Allow`, `Avoid`, and `Traffic` customize the route to meet specific needs and constraints. .

**Origin**  
The start position of the route in longitude and latitude.

**Destination**  
The end position of the route.

**Waypoints**  
Intermediate positions to include along a route between the start and end positions.

**OptimizeRoutingFor**  
Optimization criteria for the route, such as fastest or shortest.

**LegGeometryFormat**  
Format of the geometry returned for each route leg.

**Avoid**  
Features to be avoided during route calculation, ignored if no alternative route is found.

**Traffic**  
Traffic-related options affecting route calculation.

**Tolls**  
Toll-related options impacting route calculations and toll costs.

**LegAdditionalFeatures**  
Features that can be enabled within the response for each leg of the journey.

**SpanAdditionalFeatures**  
Span features that can be enabled within the response for each leg of the journey.

## Understand the response
<a name="understanding-response"></a>

The response provides route details such as the legs of the journey, notices about route calculations, and summary information including distance and duration. .

**Routes**  
Array of routes containing legs and associated properties.

**Notices**  
Warnings or informational messages about the route.

**LegGeometryFormat**  
Specifies the format of the route's geometry.

### Leg details
<a name="leg-details"></a>

Each leg of a journey can be of type Ferry, Pedestrian, or Vehicle depending on the transport mode. While each leg contains properties agnostic to transport mode, specific properties can be found under:

**FerryLegDetails**  
Ferry-specific properties for the leg.

**VehicleLegDetails**  
Vehicle-specific properties for the leg.

**PedestrianLegDetails**  
Pedestrian-specific properties for the leg.

### Steps
<a name="steps"></a>

Each leg of a journey is divided into steps that describe actions for portions of the route. A step can be either Default, suitable for basic applications, or TurnByTurn, suitable for turn-by-turn navigation. Each step contains properties agnostic to step type, such as duration and distance, and other specific properties like ExitStepDetails, which applies only to exit steps.

**BeforeTravelSteps**  
Steps to perform before beginning the journey.

**TravelSteps**  
Steps to perform during the journey.

**AfterTravelSteps**  
Steps to perform after completing the journey.

### Spans
<a name="spans"></a>

Each leg of a journey can be split into spans. A span is a portion of the leg with the same values for the set of requested `SpanAdditionalFeatures`. Spans are divided by road properties such as `SpeedLimit`, road names, or regions. Returned spans can be used to visualize road attributes and access-related information.

# Calculate toll cost
<a name="calculate-toll-cost"></a>

This topic provides an overview of the fields and definitions associated with calculating toll costs. Using these fields, you can specify parameters such as payment methods, currency, and vehicle characteristics to customize toll cost calculations.


| Field name | Routes | 
| --- | --- | 
| Transponders | Yes, with options | 
| Vignettes | Yes, with options | 
| Currency | Yes, with options | 
| EmissionType | Yes, with options | 
| VehicleCategory | Yes, with options | 

## Definitions
<a name="definitions"></a>

This section provides brief definitions for each field used in toll cost calculation.

****Transponders****  
Transponders are a method of payment for tolls, potentially resulting in a different price compared to other payment methods.

****Vignettes****  
A vignette is a form of road pricing. When a user has the required vignette, no additional toll payments are necessary.

****Currency****  
The currency in which toll costs are reported. In addition to the local currency, a converted currency is included, which also impacts the currency used in the toll summary within the response.

****EmissionType****  
The emission type of the vehicle, used for calculating toll costs based on vehicle emissions.

****VehicleCategory****  
The vehicle sub-category used for toll cost calculation.

# Understanding route steps
<a name="understanding-route-steps"></a>

This section defines various actions and steps that need to be taken to complete a leg of a journey. Route steps vary by travel mode and provide guidance for both overview applications and detailed turn-by-turn navigation.

## Route steps overview
<a name="route-steps-overview"></a>

The following types of route steps define the actions needed to complete a route leg, varying by travel mode and the stage of the journey.


| **Step type** | **Description** | 
| --- | --- | 
| Default steps | Basic steps providing human-readable instructions, often used in web-based applications to offer an overview of the route. | 
| Turn by turn steps | Detailed steps for creating a turn-by-turn navigation application, offering more granular directions. | 
| Before travel steps | Steps that need to be completed before starting the travel section, such as boarding a ferry. | 
| After travel steps | Steps to be performed after the travel section is complete, like de-boarding a ferry. | 

## Step breakdown by travel mode
<a name="route-step-types"></a>


| **Section** | **Step** | **Before Travel** | **Travel** | **After Travel** | 
| --- | --- | --- | --- | --- | 
| Vehicle | Arrive | No | Yes | No | 
| Vehicle | Continue | No | Yes | No | 
| Vehicle | ContinueHighway | No | Yes | No | 
| Vehicle | Depart | No | Yes | No | 
| Vehicle | Exit | No | Yes | No | 
| Pedestrian | Arrive | No | Yes | No | 
| Pedestrian | Charge | No | Yes | No | 
| Ferry | Wait | No | No | Yes | 
| Ferry | Board | Yes | No | No | 
| Ferry | Deboard | No | No | Yes |