libZSservicesZSamazonka-locationZSamazonka-location
Copyright(c) 2013-2021 Brendan Hay
LicenseMozilla Public License, v. 2.0.
MaintainerBrendan Hay <brendan.g.hay+amazonka@gmail.com>
Stabilityauto-generated
Portabilitynon-portable (GHC extensions)
Safe HaskellNone

Amazonka.Location.CalculateRoute

Description

Calculates a route given the following required parameters: DeparturePostiton and DestinationPosition. Requires that you first create a route calculator resource

By default, a request that doesn't specify a departure time uses the best time of day to travel with the best traffic conditions when calculating the route.

Additional options include:

  • Specifying a departure time using either DepartureTime or DepartureNow. This calculates a route based on predictive traffic data at the given time.

    You can't specify both DepartureTime and DepartureNow in a single request. Specifying both parameters returns an error message.

  • Specifying a travel mode using TravelMode. This lets you specify an additional route preference such as CarModeOptions if traveling by Car, or TruckModeOptions if traveling by Truck.
Synopsis

Creating a Request

data CalculateRoute Source #

See: newCalculateRoute smart constructor.

Constructors

CalculateRoute' 

Fields

  • distanceUnit :: Maybe DistanceUnit

    Set the unit system to specify the distance.

    Default Value: Kilometers

  • truckModeOptions :: Maybe CalculateRouteTruckModeOptions

    Specifies route preferences when traveling by Truck, such as avoiding routes that use ferries or tolls, and truck specifications to consider when choosing an optimal road.

    Requirements: TravelMode must be specified as Truck.

  • waypointPositions :: Maybe [Sensitive (NonEmpty Double)]

    Specifies an ordered list of up to 23 intermediate positions to include along a route between the departure position and destination position.

    • For example, from the DeparturePosition [-123.115, 49.285], the route follows the order that the waypoint positions are given [[-122.757, 49.0021],[-122.349, 47.620]]

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

    Specifying more than 23 waypoints returns a 400 ValidationException error.

    If Esri is the provider for your route calculator, specifying a route that is longer than 400 km returns a 400 RoutesValidationException error.

    Valid Values: [-180 to 180,-90 to 90]

  • includeLegGeometry :: Maybe Bool

    Set to include the geometry details in the result for each path between a pair of positions.

    Default Value: false

    Valid Values: false | true

  • departNow :: Maybe Bool

    Sets the time of departure as the current time. Uses the current time to calculate a route. Otherwise, the best time of day to travel with the best traffic conditions is used to calculate the route.

    Default Value: false

    Valid Values: false | true

  • travelMode :: Maybe TravelMode

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

    The TravelMode you specify determines how you specify route preferences:

    • If traveling by Car use the CarModeOptions parameter.
    • If traveling by Truck use the TruckModeOptions parameter.

    Default Value: Car

  • carModeOptions :: Maybe CalculateRouteCarModeOptions

    Specifies route preferences when traveling by Car, such as avoiding routes that use ferries or tolls.

    Requirements: TravelMode must be specified as Car.

  • departureTime :: Maybe POSIX

    Specifies the desired time of departure. Uses the given time to calculate a route. Otherwise, the best time of day to travel with the best traffic conditions is used to calculate the route.

    Setting a departure time in the past returns a 400 ValidationException error.

    • In ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ. For example, 2020–07-2T12:15:20.000Z+01:00
  • calculatorName :: Text

    The name of the route calculator resource that you want to use to calculate a route.

  • departurePosition :: Sensitive (NonEmpty Double)

    The start position for the route. Defined in WGS 84 format: [longitude, latitude].

    • For example, [-123.115, 49.285]

    If you specify a departure that's not located on a road, Amazon Location moves the position to the nearest road. If Esri is the provider for your route calculator, specifying a route that is longer than 400 km returns a 400 RoutesValidationException error.

    Valid Values: [-180 to 180,-90 to 90]

  • destinationPosition :: Sensitive (NonEmpty Double)

    The finish position for the route. Defined in WGS 84 format: [longitude, latitude].

    • For example, [-122.339, 47.615]

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

    Valid Values: [-180 to 180,-90 to 90]

Instances

Instances details
Eq CalculateRoute Source # 
Instance details

Defined in Amazonka.Location.CalculateRoute

Show CalculateRoute Source # 
Instance details

Defined in Amazonka.Location.CalculateRoute

Generic CalculateRoute Source # 
Instance details

Defined in Amazonka.Location.CalculateRoute

Associated Types

type Rep CalculateRoute :: Type -> Type #

NFData CalculateRoute Source # 
Instance details

Defined in Amazonka.Location.CalculateRoute

Methods

rnf :: CalculateRoute -> () #

Hashable CalculateRoute Source # 
Instance details

Defined in Amazonka.Location.CalculateRoute

ToJSON CalculateRoute Source # 
Instance details

Defined in Amazonka.Location.CalculateRoute

AWSRequest CalculateRoute Source # 
Instance details

Defined in Amazonka.Location.CalculateRoute

Associated Types

type AWSResponse CalculateRoute #

ToHeaders CalculateRoute Source # 
Instance details

Defined in Amazonka.Location.CalculateRoute

ToPath CalculateRoute Source # 
Instance details

Defined in Amazonka.Location.CalculateRoute

ToQuery CalculateRoute Source # 
Instance details

Defined in Amazonka.Location.CalculateRoute

type Rep CalculateRoute Source # 
Instance details

Defined in Amazonka.Location.CalculateRoute

type Rep CalculateRoute = D1 ('MetaData "CalculateRoute" "Amazonka.Location.CalculateRoute" "libZSservicesZSamazonka-locationZSamazonka-location" 'False) (C1 ('MetaCons "CalculateRoute'" 'PrefixI 'True) (((S1 ('MetaSel ('Just "distanceUnit") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 (Maybe DistanceUnit)) :*: S1 ('MetaSel ('Just "truckModeOptions") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 (Maybe CalculateRouteTruckModeOptions))) :*: (S1 ('MetaSel ('Just "waypointPositions") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 (Maybe [Sensitive (NonEmpty Double)])) :*: (S1 ('MetaSel ('Just "includeLegGeometry") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 (Maybe Bool)) :*: S1 ('MetaSel ('Just "departNow") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 (Maybe Bool))))) :*: ((S1 ('MetaSel ('Just "travelMode") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 (Maybe TravelMode)) :*: (S1 ('MetaSel ('Just "carModeOptions") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 (Maybe CalculateRouteCarModeOptions)) :*: S1 ('MetaSel ('Just "departureTime") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 (Maybe POSIX)))) :*: (S1 ('MetaSel ('Just "calculatorName") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 Text) :*: (S1 ('MetaSel ('Just "departurePosition") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 (Sensitive (NonEmpty Double))) :*: S1 ('MetaSel ('Just "destinationPosition") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 (Sensitive (NonEmpty Double))))))))
type AWSResponse CalculateRoute Source # 
Instance details

Defined in Amazonka.Location.CalculateRoute

newCalculateRoute Source #

Create a value of CalculateRoute with all optional fields omitted.

Use generic-lens or optics to modify other optional fields.

The following record fields are available, with the corresponding lenses provided for backwards compatibility:

$sel:distanceUnit:CalculateRoute', calculateRoute_distanceUnit - Set the unit system to specify the distance.

Default Value: Kilometers

$sel:truckModeOptions:CalculateRoute', calculateRoute_truckModeOptions - Specifies route preferences when traveling by Truck, such as avoiding routes that use ferries or tolls, and truck specifications to consider when choosing an optimal road.

Requirements: TravelMode must be specified as Truck.

$sel:waypointPositions:CalculateRoute', calculateRoute_waypointPositions - Specifies an ordered list of up to 23 intermediate positions to include along a route between the departure position and destination position.

  • For example, from the DeparturePosition [-123.115, 49.285], the route follows the order that the waypoint positions are given [[-122.757, 49.0021],[-122.349, 47.620]]

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

Specifying more than 23 waypoints returns a 400 ValidationException error.

If Esri is the provider for your route calculator, specifying a route that is longer than 400 km returns a 400 RoutesValidationException error.

Valid Values: [-180 to 180,-90 to 90]

$sel:includeLegGeometry:CalculateRoute', calculateRoute_includeLegGeometry - Set to include the geometry details in the result for each path between a pair of positions.

Default Value: false

Valid Values: false | true

$sel:departNow:CalculateRoute', calculateRoute_departNow - Sets the time of departure as the current time. Uses the current time to calculate a route. Otherwise, the best time of day to travel with the best traffic conditions is used to calculate the route.

Default Value: false

Valid Values: false | true

$sel:travelMode:CalculateRoute', calculateRoute_travelMode - Specifies the mode of transport when calculating a route. Used in estimating the speed of travel and road compatibility.

The TravelMode you specify determines how you specify route preferences:

  • If traveling by Car use the CarModeOptions parameter.
  • If traveling by Truck use the TruckModeOptions parameter.

Default Value: Car

$sel:carModeOptions:CalculateRoute', calculateRoute_carModeOptions - Specifies route preferences when traveling by Car, such as avoiding routes that use ferries or tolls.

Requirements: TravelMode must be specified as Car.

$sel:departureTime:CalculateRoute', calculateRoute_departureTime - Specifies the desired time of departure. Uses the given time to calculate a route. Otherwise, the best time of day to travel with the best traffic conditions is used to calculate the route.

Setting a departure time in the past returns a 400 ValidationException error.

  • In ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ. For example, 2020–07-2T12:15:20.000Z+01:00

$sel:calculatorName:CalculateRoute', calculateRoute_calculatorName - The name of the route calculator resource that you want to use to calculate a route.

$sel:departurePosition:CalculateRoute', calculateRoute_departurePosition - The start position for the route. Defined in WGS 84 format: [longitude, latitude].

  • For example, [-123.115, 49.285]

If you specify a departure that's not located on a road, Amazon Location moves the position to the nearest road. If Esri is the provider for your route calculator, specifying a route that is longer than 400 km returns a 400 RoutesValidationException error.

Valid Values: [-180 to 180,-90 to 90]

$sel:destinationPosition:CalculateRoute', calculateRoute_destinationPosition - The finish position for the route. Defined in WGS 84 format: [longitude, latitude].

  • For example, [-122.339, 47.615]

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

Valid Values: [-180 to 180,-90 to 90]

Request Lenses

calculateRoute_distanceUnit :: Lens' CalculateRoute (Maybe DistanceUnit) Source #

Set the unit system to specify the distance.

Default Value: Kilometers

calculateRoute_truckModeOptions :: Lens' CalculateRoute (Maybe CalculateRouteTruckModeOptions) Source #

Specifies route preferences when traveling by Truck, such as avoiding routes that use ferries or tolls, and truck specifications to consider when choosing an optimal road.

Requirements: TravelMode must be specified as Truck.

calculateRoute_waypointPositions :: Lens' CalculateRoute (Maybe [NonEmpty Double]) Source #

Specifies an ordered list of up to 23 intermediate positions to include along a route between the departure position and destination position.

  • For example, from the DeparturePosition [-123.115, 49.285], the route follows the order that the waypoint positions are given [[-122.757, 49.0021],[-122.349, 47.620]]

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

Specifying more than 23 waypoints returns a 400 ValidationException error.

If Esri is the provider for your route calculator, specifying a route that is longer than 400 km returns a 400 RoutesValidationException error.

Valid Values: [-180 to 180,-90 to 90]

calculateRoute_includeLegGeometry :: Lens' CalculateRoute (Maybe Bool) Source #

Set to include the geometry details in the result for each path between a pair of positions.

Default Value: false

Valid Values: false | true

calculateRoute_departNow :: Lens' CalculateRoute (Maybe Bool) Source #

Sets the time of departure as the current time. Uses the current time to calculate a route. Otherwise, the best time of day to travel with the best traffic conditions is used to calculate the route.

Default Value: false

Valid Values: false | true

calculateRoute_travelMode :: Lens' CalculateRoute (Maybe TravelMode) Source #

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

The TravelMode you specify determines how you specify route preferences:

  • If traveling by Car use the CarModeOptions parameter.
  • If traveling by Truck use the TruckModeOptions parameter.

Default Value: Car

calculateRoute_carModeOptions :: Lens' CalculateRoute (Maybe CalculateRouteCarModeOptions) Source #

Specifies route preferences when traveling by Car, such as avoiding routes that use ferries or tolls.

Requirements: TravelMode must be specified as Car.

calculateRoute_departureTime :: Lens' CalculateRoute (Maybe UTCTime) Source #

Specifies the desired time of departure. Uses the given time to calculate a route. Otherwise, the best time of day to travel with the best traffic conditions is used to calculate the route.

Setting a departure time in the past returns a 400 ValidationException error.

  • In ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ. For example, 2020–07-2T12:15:20.000Z+01:00

calculateRoute_calculatorName :: Lens' CalculateRoute Text Source #

The name of the route calculator resource that you want to use to calculate a route.

calculateRoute_departurePosition :: Lens' CalculateRoute (NonEmpty Double) Source #

The start position for the route. Defined in WGS 84 format: [longitude, latitude].

  • For example, [-123.115, 49.285]

If you specify a departure that's not located on a road, Amazon Location moves the position to the nearest road. If Esri is the provider for your route calculator, specifying a route that is longer than 400 km returns a 400 RoutesValidationException error.

Valid Values: [-180 to 180,-90 to 90]

calculateRoute_destinationPosition :: Lens' CalculateRoute (NonEmpty Double) Source #

The finish position for the route. Defined in WGS 84 format: [longitude, latitude].

  • For example, [-122.339, 47.615]

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

Valid Values: [-180 to 180,-90 to 90]

Destructuring the Response

data CalculateRouteResponse Source #

Returns the result of the route calculation. Metadata includes legs and route summary.

See: newCalculateRouteResponse smart constructor.

Constructors

CalculateRouteResponse' 

Fields

  • httpStatus :: Int

    The response's http status code.

  • legs :: [Leg]

    Contains details about each path between a pair of positions included along a route such as: StartPosition, EndPosition, Distance, DurationSeconds, Geometry, and Steps. The number of legs returned corresponds to one fewer than the total number of positions in the request.

    For example, a route with a departure position and destination position returns one leg with the positions snapped to a nearby road:

    • The StartPosition is the departure position.
    • The EndPosition is the destination position.

    A route with a waypoint between the departure and destination position returns two legs with the positions snapped to a nearby road:

    • Leg 1: The StartPosition is the departure position . The EndPosition is the waypoint positon.
    • Leg 2: The StartPosition is the waypoint position. The EndPosition is the destination position.
  • summary :: CalculateRouteSummary

    Contains information about the whole route, such as: RouteBBox, DataSource, Distance, DistanceUnit, and DurationSeconds.

Instances

Instances details
Eq CalculateRouteResponse Source # 
Instance details

Defined in Amazonka.Location.CalculateRoute

Show CalculateRouteResponse Source # 
Instance details

Defined in Amazonka.Location.CalculateRoute

Generic CalculateRouteResponse Source # 
Instance details

Defined in Amazonka.Location.CalculateRoute

Associated Types

type Rep CalculateRouteResponse :: Type -> Type #

NFData CalculateRouteResponse Source # 
Instance details

Defined in Amazonka.Location.CalculateRoute

Methods

rnf :: CalculateRouteResponse -> () #

type Rep CalculateRouteResponse Source # 
Instance details

Defined in Amazonka.Location.CalculateRoute

type Rep CalculateRouteResponse = D1 ('MetaData "CalculateRouteResponse" "Amazonka.Location.CalculateRoute" "libZSservicesZSamazonka-locationZSamazonka-location" 'False) (C1 ('MetaCons "CalculateRouteResponse'" 'PrefixI 'True) (S1 ('MetaSel ('Just "httpStatus") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 Int) :*: (S1 ('MetaSel ('Just "legs") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 [Leg]) :*: S1 ('MetaSel ('Just "summary") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 CalculateRouteSummary))))

newCalculateRouteResponse Source #

Create a value of CalculateRouteResponse with all optional fields omitted.

Use generic-lens or optics to modify other optional fields.

The following record fields are available, with the corresponding lenses provided for backwards compatibility:

$sel:httpStatus:CalculateRouteResponse', calculateRouteResponse_httpStatus - The response's http status code.

$sel:legs:CalculateRouteResponse', calculateRouteResponse_legs - Contains details about each path between a pair of positions included along a route such as: StartPosition, EndPosition, Distance, DurationSeconds, Geometry, and Steps. The number of legs returned corresponds to one fewer than the total number of positions in the request.

For example, a route with a departure position and destination position returns one leg with the positions snapped to a nearby road:

  • The StartPosition is the departure position.
  • The EndPosition is the destination position.

A route with a waypoint between the departure and destination position returns two legs with the positions snapped to a nearby road:

  • Leg 1: The StartPosition is the departure position . The EndPosition is the waypoint positon.
  • Leg 2: The StartPosition is the waypoint position. The EndPosition is the destination position.

$sel:summary:CalculateRouteResponse', calculateRouteResponse_summary - Contains information about the whole route, such as: RouteBBox, DataSource, Distance, DistanceUnit, and DurationSeconds.

Response Lenses

calculateRouteResponse_legs :: Lens' CalculateRouteResponse [Leg] Source #

Contains details about each path between a pair of positions included along a route such as: StartPosition, EndPosition, Distance, DurationSeconds, Geometry, and Steps. The number of legs returned corresponds to one fewer than the total number of positions in the request.

For example, a route with a departure position and destination position returns one leg with the positions snapped to a nearby road:

  • The StartPosition is the departure position.
  • The EndPosition is the destination position.

A route with a waypoint between the departure and destination position returns two legs with the positions snapped to a nearby road:

  • Leg 1: The StartPosition is the departure position . The EndPosition is the waypoint positon.
  • Leg 2: The StartPosition is the waypoint position. The EndPosition is the destination position.

calculateRouteResponse_summary :: Lens' CalculateRouteResponse CalculateRouteSummary Source #

Contains information about the whole route, such as: RouteBBox, DataSource, Distance, DistanceUnit, and DurationSeconds.