CalculateRoutes - Amazon Location Service

CalculateRoutes

CalculateRoutes computes routes given the following required parameters: Origin and Destination.

Request Syntax

POST /routes?key=Key HTTP/1.1 Content-type: application/json { "Allow": { "Hot": boolean, "Hov": boolean }, "ArrivalTime": "string", "Avoid": { "Areas": [ { "Except": [ { "BoundingBox": [ number ], "Corridor": { "LineString": [ [ number ] ], "Radius": number }, "Polygon": [ [ [ number ] ] ], "PolylineCorridor": { "Polyline": "string", "Radius": number }, "PolylinePolygon": [ "string" ] } ], "Geometry": { "BoundingBox": [ number ], "Corridor": { "LineString": [ [ number ] ], "Radius": number }, "Polygon": [ [ [ number ] ] ], "PolylineCorridor": { "Polyline": "string", "Radius": number }, "PolylinePolygon": [ "string" ] } } ], "CarShuttleTrains": boolean, "ControlledAccessHighways": boolean, "DirtRoads": boolean, "Ferries": boolean, "SeasonalClosure": boolean, "TollRoads": boolean, "TollTransponders": boolean, "TruckRoadTypes": [ "string" ], "Tunnels": boolean, "UTurns": boolean, "ZoneCategories": [ { "Category": "string" } ] }, "DepartNow": boolean, "DepartureTime": "string", "Destination": [ number ], "DestinationOptions": { "AvoidActionsForDistance": number, "AvoidUTurns": boolean, "Heading": number, "Matching": { "NameHint": "string", "OnRoadThreshold": number, "Radius": number, "Strategy": "string" }, "SideOfStreet": { "Position": [ number ], "UseWith": "string" }, "StopDuration": number }, "Driver": { "Schedule": [ { "DriveDuration": number, "RestDuration": number } ] }, "Exclude": { "Countries": [ "string" ] }, "InstructionsMeasurementSystem": "string", "Languages": [ "string" ], "LegAdditionalFeatures": [ "string" ], "LegGeometryFormat": "string", "MaxAlternatives": number, "OptimizeRoutingFor": "string", "Origin": [ number ], "OriginOptions": { "AvoidActionsForDistance": number, "AvoidUTurns": boolean, "Heading": number, "Matching": { "NameHint": "string", "OnRoadThreshold": number, "Radius": number, "Strategy": "string" }, "SideOfStreet": { "Position": [ number ], "UseWith": "string" } }, "SpanAdditionalFeatures": [ "string" ], "Tolls": { "AllTransponders": boolean, "AllVignettes": boolean, "Currency": "string", "EmissionType": { "Co2EmissionClass": "string", "Type": "string" }, "VehicleCategory": "string" }, "Traffic": { "FlowEventThresholdOverride": number, "Usage": "string" }, "TravelMode": "string", "TravelModeOptions": { "Car": { "EngineType": "string", "LicensePlate": { "LastCharacter": "string" }, "MaxSpeed": number, "Occupancy": number }, "Pedestrian": { "Speed": number }, "Scooter": { "EngineType": "string", "LicensePlate": { "LastCharacter": "string" }, "MaxSpeed": number, "Occupancy": number }, "Truck": { "AxleCount": number, "EngineType": "string", "GrossWeight": number, "HazardousCargos": [ "string" ], "Height": number, "HeightAboveFirstAxle": number, "KpraLength": number, "Length": number, "LicensePlate": { "LastCharacter": "string" }, "MaxSpeed": number, "Occupancy": number, "PayloadCapacity": number, "TireCount": number, "Trailer": { "AxleCount": number, "TrailerCount": number }, "TruckType": "string", "TunnelRestrictionCode": "string", "WeightPerAxle": number, "WeightPerAxleGroup": { "Quad": number, "Quint": number, "Single": number, "Tandem": number, "Triple": number }, "Width": number } }, "TravelStepType": "string", "Waypoints": [ { "AvoidActionsForDistance": number, "AvoidUTurns": boolean, "Heading": number, "Matching": { "NameHint": "string", "OnRoadThreshold": number, "Radius": number, "Strategy": "string" }, "PassThrough": boolean, "Position": [ number ], "SideOfStreet": { "Position": [ number ], "UseWith": "string" }, "StopDuration": number } ] }

URI Request Parameters

The request uses the following URI parameters.

Key

Optional: The API key to be used for authorization. Either an API key or valid SigV4 signature must be provided when making a request.

Length Constraints: Minimum length of 0. Maximum length of 1000.

Request Body

The request accepts the following data in JSON format.

Allow

Features that are allowed while calculating a route.

Type: RouteAllowOptions object

Required: No

ArrivalTime

Time of arrival at the destination.

Time format:YYYY-MM-DDThh:mm:ss.sssZ | YYYY-MM-DDThh:mm:ss.sss+hh:mm

Examples:

2020-04-22T17:57:24Z

2020-04-22T17:57:24+02:00

Type: String

Pattern: ([1-2][0-9]{3})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9]|60)(\.[0-9]{0,9})?(Z|[+-]([01][0-9]|2[0-3]):[0-5][0-9])

Required: No

Avoid

Features that are avoided while calculating a route. Avoidance is on a best-case basis. If an avoidance can't be satisfied for a particular case, it violates the avoidance and the returned response produces a notice for the violation.

Type: RouteAvoidanceOptions object

Required: No

DepartNow

Uses the current time as the time of departure.

Type: Boolean

Required: No

DepartureTime

Time of departure from thr origin.

Time format:YYYY-MM-DDThh:mm:ss.sssZ | YYYY-MM-DDThh:mm:ss.sss+hh:mm

Examples:

2020-04-22T17:57:24Z

2020-04-22T17:57:24+02:00

Type: String

Pattern: ([1-2][0-9]{3})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9]|60)(\.[0-9]{0,9})?(Z|[+-]([01][0-9]|2[0-3]):[0-5][0-9])

Required: No

Destination

The final position for the route. In the World Geodetic System (WGS 84) format: [longitude, latitude].

Type: Array of doubles

Array Members: Fixed number of 2 items.

Required: Yes

DestinationOptions

Destination related options.

Type: RouteDestinationOptions object

Required: No

Driver

Driver related options.

Type: RouteDriverOptions object

Required: No

Exclude

Features to be strictly excluded while calculating the route.

Type: RouteExclusionOptions object

Required: No

InstructionsMeasurementSystem

Measurement system to be used for instructions within steps in the response.

Type: String

Valid Values: Metric | Imperial

Required: No

Languages

List of languages for instructions within steps in the response.

Note

Instructions in the requested language are returned only if they are available.

Type: Array of strings

Array Members: Minimum number of 0 items. Maximum number of 10 items.

Length Constraints: Minimum length of 2. Maximum length of 35.

Required: No

LegAdditionalFeatures

A list of optional additional parameters such as timezone that can be requested for each result.

  • Elevation: Retrieves the elevation information for each location.

  • Incidents: Provides information on traffic incidents along the route.

  • PassThroughWaypoints: Indicates waypoints that are passed through without stopping.

  • Summary: Returns a summary of the route, including distance and duration.

  • Tolls: Supplies toll cost information along the route.

  • TravelStepInstructions: Provides step-by-step instructions for travel along the route.

  • TruckRoadTypes: Returns information about road types suitable for trucks.

  • TypicalDuration: Gives typical travel duration based on historical data.

  • Zones: Specifies the time zone information for each waypoint.

Type: Array of strings

Array Members: Minimum number of 0 items. Maximum number of 9 items.

Valid Values: Elevation | Incidents | PassThroughWaypoints | Summary | Tolls | TravelStepInstructions | TruckRoadTypes | TypicalDuration | Zones

Required: No

LegGeometryFormat

Specifies the format of the geometry returned for each leg of the route. You can choose between two different geometry encoding formats.

FlexiblePolyline: A compact and precise encoding format for the leg geometry. For more information on the format, see the GitHub repository for FlexiblePolyline.

Simple: A less compact encoding, which is easier to decode but may be less precise and result in larger payloads.

Type: String

Valid Values: FlexiblePolyline | Simple

Required: No

MaxAlternatives

Maximum number of alternative routes to be provided in the response, if available.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 5.

Required: No

OptimizeRoutingFor

Specifies the optimization criteria for calculating a route.

Default Value: FastestRoute

Type: String

Valid Values: FastestRoute | ShortestRoute

Required: No

Origin

The start position for the route.

Type: Array of doubles

Array Members: Fixed number of 2 items.

Required: Yes

OriginOptions

Origin related options.

Type: RouteOriginOptions object

Required: No

SpanAdditionalFeatures

A list of optional features such as SpeedLimit that can be requested for a Span. A span is a section of a Leg for which the requested features have the same values.

Type: Array of strings

Array Members: Minimum number of 0 items. Maximum number of 24 items.

Valid Values: BestCaseDuration | CarAccess | Country | Distance | Duration | DynamicSpeed | FunctionalClassification | Gates | Incidents | Names | Notices | PedestrianAccess | RailwayCrossings | Region | RoadAttributes | RouteNumbers | ScooterAccess | SpeedLimit | TollSystems | TruckAccess | TruckRoadTypes | TypicalDuration | Zones | Consumption

Required: No

Tolls

Toll related options.

Type: RouteTollOptions object

Required: No

Traffic

Traffic related options.

Type: RouteTrafficOptions object

Required: No

TravelMode

Specifies the mode of transport when calculating a route. Used in estimating the speed of travel and road compatibility.

Default Value: Car

Type: String

Valid Values: Car | Pedestrian | Scooter | Truck

Required: No

TravelModeOptions

Travel mode related options for the provided travel mode.

Type: RouteTravelModeOptions object

Required: No

TravelStepType

Type of step returned by the response. Default provides basic steps intended for web based applications. TurnByTurn provides detailed instructions with more granularity intended for a turn based naviagtion system.

Type: String

Valid Values: Default | TurnByTurn

Required: No

Waypoints

List of waypoints between the Origin and Destination.

Type: Array of RouteWaypoint objects

Required: No

Response Syntax

HTTP/1.1 200 x-amz-geo-pricing-bucket: PricingBucket Content-type: application/json { "LegGeometryFormat": "string", "Notices": [ { "Code": "string", "Impact": "string" } ], "Routes": [ { "Legs": [ { "FerryLegDetails": { "AfterTravelSteps": [ { "Duration": number, "Instruction": "string", "Type": "string" } ], "Arrival": { "Place": { "Name": "string", "OriginalPosition": [ number ], "Position": [ number ], "WaypointIndex": number }, "Time": "string" }, "BeforeTravelSteps": [ { "Duration": number, "Instruction": "string", "Type": "string" } ], "Departure": { "Place": { "Name": "string", "OriginalPosition": [ number ], "Position": [ number ], "WaypointIndex": number }, "Time": "string" }, "Notices": [ { "Code": "string", "Impact": "string" } ], "PassThroughWaypoints": [ { "GeometryOffset": number, "Place": { "OriginalPosition": [ number ], "Position": [ number ], "WaypointIndex": number } } ], "RouteName": "string", "Spans": [ { "Country": "string", "Distance": number, "Duration": number, "GeometryOffset": number, "Names": [ { "Language": "string", "Value": "string" } ], "Region": "string" } ], "Summary": { "Overview": { "Distance": number, "Duration": number }, "TravelOnly": { "Duration": number } }, "TravelSteps": [ { "Distance": number, "Duration": number, "GeometryOffset": number, "Instruction": "string", "Type": "string" } ] }, "Geometry": { "LineString": [ [ number ] ], "Polyline": "string" }, "Language": "string", "PedestrianLegDetails": { "Arrival": { "Place": { "Name": "string", "OriginalPosition": [ number ], "Position": [ number ], "SideOfStreet": "string", "WaypointIndex": number }, "Time": "string" }, "Departure": { "Place": { "Name": "string", "OriginalPosition": [ number ], "Position": [ number ], "SideOfStreet": "string", "WaypointIndex": number }, "Time": "string" }, "Notices": [ { "Code": "string", "Impact": "string" } ], "PassThroughWaypoints": [ { "GeometryOffset": number, "Place": { "OriginalPosition": [ number ], "Position": [ number ], "WaypointIndex": number } } ], "Spans": [ { "BestCaseDuration": number, "Country": "string", "Distance": number, "Duration": number, "DynamicSpeed": { "BestCaseSpeed": number, "TurnDuration": number, "TypicalSpeed": number }, "FunctionalClassification": number, "GeometryOffset": number, "Incidents": [ number ], "Names": [ { "Language": "string", "Value": "string" } ], "PedestrianAccess": [ "string" ], "Region": "string", "RoadAttributes": [ "string" ], "RouteNumbers": [ { "Direction": "string", "Language": "string", "Value": "string" } ], "SpeedLimit": { "MaxSpeed": number, "Unlimited": boolean }, "TypicalDuration": number } ], "Summary": { "Overview": { "Distance": number, "Duration": number }, "TravelOnly": { "Duration": number } }, "TravelSteps": [ { "ContinueStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ] }, "CurrentRoad": { "RoadName": [ { "Language": "string", "Value": "string" } ], "RouteNumber": [ { "Direction": "string", "Language": "string", "Value": "string" } ], "Towards": [ { "Language": "string", "Value": "string" } ], "Type": "string" }, "Distance": number, "Duration": number, "ExitNumber": [ { "Language": "string", "Value": "string" } ], "GeometryOffset": number, "Instruction": "string", "KeepStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "SteeringDirection": "string", "TurnAngle": number, "TurnIntensity": "string" }, "NextRoad": { "RoadName": [ { "Language": "string", "Value": "string" } ], "RouteNumber": [ { "Direction": "string", "Language": "string", "Value": "string" } ], "Towards": [ { "Language": "string", "Value": "string" } ], "Type": "string" }, "RoundaboutEnterStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "SteeringDirection": "string", "TurnAngle": number, "TurnIntensity": "string" }, "RoundaboutExitStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "RelativeExit": number, "RoundaboutAngle": number, "SteeringDirection": "string" }, "RoundaboutPassStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "SteeringDirection": "string", "TurnAngle": number, "TurnIntensity": "string" }, "Signpost": { "Labels": [ { "RouteNumber": { "Direction": "string", "Language": "string", "Value": "string" }, "Text": { "Language": "string", "Value": "string" } } ] }, "TurnStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "SteeringDirection": "string", "TurnAngle": number, "TurnIntensity": "string" }, "Type": "string" } ] }, "TravelMode": "string", "Type": "string", "VehicleLegDetails": { "Arrival": { "Place": { "Name": "string", "OriginalPosition": [ number ], "Position": [ number ], "SideOfStreet": "string", "WaypointIndex": number }, "Time": "string" }, "Departure": { "Place": { "Name": "string", "OriginalPosition": [ number ], "Position": [ number ], "SideOfStreet": "string", "WaypointIndex": number }, "Time": "string" }, "Incidents": [ { "Description": "string", "EndTime": "string", "Severity": "string", "StartTime": "string", "Type": "string" } ], "Notices": [ { "Code": "string", "Details": [ { "Title": "string", "ViolatedConstraints": { "AllHazardsRestricted": boolean, "AxleCount": { "Max": number, "Min": number }, "HazardousCargos": [ "string" ], "MaxHeight": number, "MaxKpraLength": number, "MaxLength": number, "MaxPayloadCapacity": number, "MaxWeight": { "Type": "string", "Value": number }, "MaxWeightPerAxle": number, "MaxWeightPerAxleGroup": { "Quad": number, "Quint": number, "Single": number, "Tandem": number, "Triple": number }, "MaxWidth": number, "Occupancy": { "Max": number, "Min": number }, "RestrictedTimes": "string", "TimeDependent": boolean, "TrailerCount": { "Max": number, "Min": number }, "TravelMode": boolean, "TruckRoadType": "string", "TruckType": "string", "TunnelRestrictionCode": "string" } } ], "Impact": "string" } ], "PassThroughWaypoints": [ { "GeometryOffset": number, "Place": { "OriginalPosition": [ number ], "Position": [ number ], "WaypointIndex": number } } ], "Spans": [ { "BestCaseDuration": number, "CarAccess": [ "string" ], "Country": "string", "Distance": number, "Duration": number, "DynamicSpeed": { "BestCaseSpeed": number, "TurnDuration": number, "TypicalSpeed": number }, "FunctionalClassification": number, "Gate": "string", "GeometryOffset": number, "Incidents": [ number ], "Names": [ { "Language": "string", "Value": "string" } ], "Notices": [ number ], "RailwayCrossing": "string", "Region": "string", "RoadAttributes": [ "string" ], "RouteNumbers": [ { "Direction": "string", "Language": "string", "Value": "string" } ], "ScooterAccess": [ "string" ], "SpeedLimit": { "MaxSpeed": number, "Unlimited": boolean }, "TollSystems": [ number ], "TruckAccess": [ "string" ], "TruckRoadTypes": [ number ], "TypicalDuration": number, "Zones": [ number ] } ], "Summary": { "Overview": { "BestCaseDuration": number, "Distance": number, "Duration": number, "TypicalDuration": number }, "TravelOnly": { "BestCaseDuration": number, "Duration": number, "TypicalDuration": number } }, "Tolls": [ { "Country": "string", "PaymentSites": [ { "Name": "string", "Position": [ number ] } ], "Rates": [ { "ApplicableTimes": "string", "ConvertedPrice": { "Currency": "string", "Estimate": boolean, "PerDuration": number, "Range": boolean, "RangeValue": { "Max": number, "Min": number }, "Value": number }, "Id": "string", "LocalPrice": { "Currency": "string", "Estimate": boolean, "PerDuration": number, "Range": boolean, "RangeValue": { "Max": number, "Min": number }, "Value": number }, "Name": "string", "Pass": { "IncludesReturnTrip": boolean, "SeniorPass": boolean, "TransferCount": number, "TripCount": number, "ValidityPeriod": { "Period": "string", "PeriodCount": number } }, "PaymentMethods": [ "string" ], "Transponders": [ { "SystemName": "string" } ] } ], "Systems": [ number ] } ], "TollSystems": [ { "Name": "string" } ], "TravelSteps": [ { "ContinueHighwayStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "SteeringDirection": "string", "TurnAngle": number, "TurnIntensity": "string" }, "ContinueStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ] }, "CurrentRoad": { "RoadName": [ { "Language": "string", "Value": "string" } ], "RouteNumber": [ { "Direction": "string", "Language": "string", "Value": "string" } ], "Towards": [ { "Language": "string", "Value": "string" } ], "Type": "string" }, "Distance": number, "Duration": number, "EnterHighwayStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "SteeringDirection": "string", "TurnAngle": number, "TurnIntensity": "string" }, "ExitNumber": [ { "Language": "string", "Value": "string" } ], "ExitStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "RelativeExit": number, "SteeringDirection": "string", "TurnAngle": number, "TurnIntensity": "string" }, "GeometryOffset": number, "Instruction": "string", "KeepStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "SteeringDirection": "string", "TurnAngle": number, "TurnIntensity": "string" }, "NextRoad": { "RoadName": [ { "Language": "string", "Value": "string" } ], "RouteNumber": [ { "Direction": "string", "Language": "string", "Value": "string" } ], "Towards": [ { "Language": "string", "Value": "string" } ], "Type": "string" }, "RampStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "SteeringDirection": "string", "TurnAngle": number, "TurnIntensity": "string" }, "RoundaboutEnterStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "SteeringDirection": "string", "TurnAngle": number, "TurnIntensity": "string" }, "RoundaboutExitStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "RelativeExit": number, "RoundaboutAngle": number, "SteeringDirection": "string" }, "RoundaboutPassStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "SteeringDirection": "string", "TurnAngle": number, "TurnIntensity": "string" }, "Signpost": { "Labels": [ { "RouteNumber": { "Direction": "string", "Language": "string", "Value": "string" }, "Text": { "Language": "string", "Value": "string" } } ] }, "TurnStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "SteeringDirection": "string", "TurnAngle": number, "TurnIntensity": "string" }, "Type": "string", "UTurnStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "SteeringDirection": "string", "TurnAngle": number, "TurnIntensity": "string" } } ], "TruckRoadTypes": [ "string" ], "Zones": [ { "Category": "string", "Name": "string" } ] } } ], "MajorRoadLabels": [ { "RoadName": { "Language": "string", "Value": "string" }, "RouteNumber": { "Direction": "string", "Language": "string", "Value": "string" } } ], "Summary": { "Distance": number, "Duration": number, "Tolls": { "Total": { "Currency": "string", "Estimate": boolean, "Range": boolean, "RangeValue": { "Max": number, "Min": number }, "Value": number } } } } ] }

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The response returns the following HTTP headers.

PricingBucket

The pricing bucket for which the query is charged at.

The following data is returned in JSON format by the service.

LegGeometryFormat

Specifies the format of the geometry returned for each leg of the route.

Type: String

Valid Values: FlexiblePolyline | Simple

Notices

Notices are additional information returned that indicate issues that occurred during route calculation.

Type: Array of RouteResponseNotice objects

Routes

The path from the origin to the destination.

Type: Array of Route objects

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have sufficient access to perform this action.

HTTP Status Code: 403

InternalServerException

The request processing has failed because of an unknown error, exception or failure.

HTTP Status Code: 500

ThrottlingException

The request was denied due to request throttling.

HTTP Status Code: 429

ValidationException

The input fails to satisfy the constraints specified by an AWS service.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: