LocationServiceRoutesV2 / Client / optimize_waypoints

optimize_waypoints

LocationServiceRoutesV2.Client.optimize_waypoints(**kwargs)

Calculates the optimal order to travel between a set of waypoints to minimize either the travel time or the distance travelled during the journey, based on road network restrictions and the traffic pattern data.

See also: AWS API Documentation

Request Syntax

response = client.optimize_waypoints(
    Avoid={
        'Areas': [
            {
                'Geometry': {
                    'BoundingBox': [
                        123.0,
                    ]
                }
            },
        ],
        'CarShuttleTrains': True|False,
        'ControlledAccessHighways': True|False,
        'DirtRoads': True|False,
        'Ferries': True|False,
        'TollRoads': True|False,
        'Tunnels': True|False,
        'UTurns': True|False
    },
    DepartureTime='string',
    Destination=[
        123.0,
    ],
    DestinationOptions={
        'AccessHours': {
            'From': {
                'DayOfWeek': 'Monday'|'Tuesday'|'Wednesday'|'Thursday'|'Friday'|'Saturday'|'Sunday',
                'TimeOfDay': 'string'
            },
            'To': {
                'DayOfWeek': 'Monday'|'Tuesday'|'Wednesday'|'Thursday'|'Friday'|'Saturday'|'Sunday',
                'TimeOfDay': 'string'
            }
        },
        'AppointmentTime': 'string',
        'Heading': 123.0,
        'Id': 'string',
        'ServiceDuration': 123,
        'SideOfStreet': {
            'Position': [
                123.0,
            ],
            'UseWith': 'AnyStreet'|'DividedStreetOnly'
        }
    },
    Driver={
        'RestCycles': {
            'LongCycle': {
                'RestDuration': 123,
                'WorkDuration': 123
            },
            'ShortCycle': {
                'RestDuration': 123,
                'WorkDuration': 123
            }
        },
        'RestProfile': {
            'Profile': 'string'
        },
        'TreatServiceTimeAs': 'Rest'|'Work'
    },
    Exclude={
        'Countries': [
            'string',
        ]
    },
    Key='string',
    OptimizeSequencingFor='FastestRoute'|'ShortestRoute',
    Origin=[
        123.0,
    ],
    OriginOptions={
        'Id': 'string'
    },
    Traffic={
        'Usage': 'IgnoreTrafficData'|'UseTrafficData'
    },
    TravelMode='Car'|'Pedestrian'|'Scooter'|'Truck',
    TravelModeOptions={
        'Pedestrian': {
            'Speed': 123.0
        },
        'Truck': {
            'GrossWeight': 123,
            'HazardousCargos': [
                'Combustible'|'Corrosive'|'Explosive'|'Flammable'|'Gas'|'HarmfulToWater'|'Organic'|'Other'|'Poison'|'PoisonousInhalation'|'Radioactive',
            ],
            'Height': 123,
            'Length': 123,
            'Trailer': {
                'TrailerCount': 123
            },
            'TruckType': 'StraightTruck'|'Tractor',
            'TunnelRestrictionCode': 'string',
            'WeightPerAxle': 123,
            'Width': 123
        }
    },
    Waypoints=[
        {
            'AccessHours': {
                'From': {
                    'DayOfWeek': 'Monday'|'Tuesday'|'Wednesday'|'Thursday'|'Friday'|'Saturday'|'Sunday',
                    'TimeOfDay': 'string'
                },
                'To': {
                    'DayOfWeek': 'Monday'|'Tuesday'|'Wednesday'|'Thursday'|'Friday'|'Saturday'|'Sunday',
                    'TimeOfDay': 'string'
                }
            },
            'AppointmentTime': 'string',
            'Before': [
                123,
            ],
            'Heading': 123.0,
            'Id': 'string',
            'Position': [
                123.0,
            ],
            'ServiceDuration': 123,
            'SideOfStreet': {
                'Position': [
                    123.0,
                ],
                'UseWith': 'AnyStreet'|'DividedStreetOnly'
            }
        },
    ]
)

Parameters:

• Avoid (dict) –

  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, this setting is ignored.

  • Areas (list) –

    Areas to be avoided.

    • (dict) –

      The area to be avoided.

      • Geometry (dict) – [REQUIRED]

        Geometry of the area to be avoided.

        • BoundingBox (list) –

          Geometry defined as a bounding box. The first pair represents the X and Y coordinates (longitude and latitude,) of the southwest corner of the bounding box; the second pair represents the X and Y coordinates (longitude and latitude) of the northeast corner.

          • (float) –

  • CarShuttleTrains (boolean) –

    Avoidance options for cars-shuttles-trains.

  • ControlledAccessHighways (boolean) –

    Avoid controlled access highways while calculating the route.

  • DirtRoads (boolean) –

    Avoid dirt roads while calculating the route.

  • Ferries (boolean) –

    Avoidance options for ferries.

  • TollRoads (boolean) –

    Avoids roads where the specified toll transponders are the only mode of payment.

  • Tunnels (boolean) –

    Avoid tunnels while calculating the route.

  • UTurns (boolean) –

    Avoid U-turns for calculation on highways and motorways.

• DepartureTime (string) –

  Departure time from the waypoint.

  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

• Destination (list) –

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

  • (float) –

• DestinationOptions (dict) –

  Destination related options.

  • AccessHours (dict) –

    Access hours corresponding to when a waypoint can be visited.

    • From (dict) – [REQUIRED]

      Contains the ID of the starting waypoint in this connection.

      • DayOfWeek (string) – [REQUIRED]

        Day of the week.

      • TimeOfDay (string) – [REQUIRED]

        Time of the day.

    • To (dict) – [REQUIRED]

      Contains the ID of the ending waypoint in this connection.

      • DayOfWeek (string) – [REQUIRED]

        Day of the week.

      • TimeOfDay (string) – [REQUIRED]

        Time of the day.

  • AppointmentTime (string) –

    Appointment time at the destination.

  • Heading (float) –

    GPS Heading at the position.

  • Id (string) –

    The waypoint Id.

  • ServiceDuration (integer) –

    Service time spent at the destination. At an appointment, the service time should be the appointment duration.

    Unit: seconds

  • SideOfStreet (dict) –

    Options to configure matching the provided position to a side of the street.

    • Position (list) – [REQUIRED]

      Position defined as [longitude, latitude].

      • (float) –

    • UseWith (string) –

      Strategy that defines when the side of street position should be used. AnyStreet will always use the provided position.

      Default Value: DividedStreetOnly

• Driver (dict) –

  Driver related options.

  • RestCycles (dict) –

    Driver work-rest schedules defined by a short and long cycle. A rest needs to be taken after the short work duration. The short cycle can be repeated until you hit the long work duration, at which point the long rest duration should be taken before restarting.

    • LongCycle (dict) – [REQUIRED]

      Long cycle for a driver work-rest schedule.

      • RestDuration (integer) – [REQUIRED]

        Resting phase of the cycle.

        Unit: seconds

      • WorkDuration (integer) – [REQUIRED]

        Working phase of the cycle.

        Unit: seconds

    • ShortCycle (dict) – [REQUIRED]

      Short cycle for a driver work-rest schedule

      • RestDuration (integer) – [REQUIRED]

        Resting phase of the cycle.

        Unit: seconds

      • WorkDuration (integer) – [REQUIRED]

        Working phase of the cycle.

        Unit: seconds

  • RestProfile (dict) –

    Pre defined rest profiles for a driver schedule. The only currently supported profile is EU.

    • Profile (string) – [REQUIRED]

      Pre defined rest profiles for a driver schedule. The only currently supported profile is EU.

  • TreatServiceTimeAs (string) –

    If the service time provided at a waypoint/destination should be considered as rest or work. This contributes to the total time breakdown returned within the response.

• Exclude (dict) –

  Features to be strictly excluded while calculating the route.

  • Countries (list) – [REQUIRED]

    List of countries to be avoided defined by two-letter or three-letter country codes.

    • (string) –

• Key (string) – Optional: The API key to be used for authorization. Either an API key or valid SigV4 signature must be provided when making a request.

• OptimizeSequencingFor (string) –

  Specifies the optimization criteria for the calculated sequence.

  Default Value: FastestRoute.

• Origin (list) –

  [REQUIRED]

  The start position for the route.

  • (float) –

• OriginOptions (dict) –

  Origin related options.

  • Id (string) –

    The Origin Id.

• Traffic (dict) –

  Traffic-related options.

  • Usage (string) –

    Determines if traffic should be used or ignored while calculating the route.

    Default Value: UseTrafficData

• TravelMode (string) –

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

  Default Value: Car

• TravelModeOptions (dict) –

  Travel mode related options for the provided travel mode.

  • Pedestrian (dict) –

    Travel mode options when the provided travel mode is “Pedestrian”

    • Speed (float) –

      Walking speed.

      Unit: KilometersPerHour

  • Truck (dict) –

    Travel mode options when the provided travel mode is “Truck”

    • GrossWeight (integer) –

      Gross weight of the vehicle including trailers, and goods at capacity.

      Unit: Kilograms

    • HazardousCargos (list) –

      List of Hazardous cargo contained in the vehicle.

      • (string) –

    • Height (integer) –

      Height of the vehicle.

      Unit: centimeters

    • Length (integer) –

      Length of the vehicle.

      Unit: centimeters

    • Trailer (dict) –

      Trailer options corresponding to the vehicle.

      • TrailerCount (integer) –

        Number of trailers attached to the vehicle.

        Default Value: 0

    • TruckType (string) –

      Type of the truck.

    • TunnelRestrictionCode (string) –

      The tunnel restriction code.

      Tunnel categories in this list indicate the restrictions which apply to certain tunnels in Great Britain. They relate to the types of dangerous goods that can be transported through them.

      • Tunnel Category B

        • Risk Level: Limited risk

        • Restrictions: Few restrictions

      • Tunnel Category C

        • Risk Level: Medium risk

        • Restrictions: Some restrictions

      • Tunnel Category D

        • Risk Level: High risk

        • Restrictions: Many restrictions occur

      • Tunnel Category E

        • Risk Level: Very high risk

        • Restrictions: Restricted tunnel

    • WeightPerAxle (integer) –

      Heaviest weight per axle irrespective of the axle type or the axle group. Meant for usage in countries where the differences in axle types or axle groups are not distinguished.

      Unit: Kilograms

    • Width (integer) –

      Width of the vehicle.

      Unit: centimeters

• Waypoints (list) –

  List of waypoints between the Origin and Destination.

  • (dict) –

    Waypoint between the Origin and Destination.

    • AccessHours (dict) –

      Access hours corresponding to when a waypoint can be visited.

      • From (dict) – [REQUIRED]

        Contains the ID of the starting waypoint in this connection.

        • DayOfWeek (string) – [REQUIRED]

          Day of the week.

        • TimeOfDay (string) – [REQUIRED]

          Time of the day.

      • To (dict) – [REQUIRED]

        Contains the ID of the ending waypoint in this connection.

        • DayOfWeek (string) – [REQUIRED]

          Day of the week.

        • TimeOfDay (string) – [REQUIRED]

          Time of the day.

    • AppointmentTime (string) –

      Appointment time at the waypoint.

    • Before (list) –

      Constraint defining what waypoints are to be visited after this waypoint.

      • (integer) –

    • Heading (float) –

      GPS Heading at the position.

    • Id (string) –

      The waypoint Id.

    • Position (list) – [REQUIRED]

      Position defined as [longitude, latitude].

      • (float) –

    • ServiceDuration (integer) –

      Service time spent at the waypoint. At an appointment, the service time should be the appointment duration.

      Unit: seconds

    • SideOfStreet (dict) –

      Options to configure matching the provided position to a side of the street.

      • Position (list) – [REQUIRED]

        Position defined as [longitude, latitude].

        • (float) –

      • UseWith (string) –

        Strategy that defines when the side of street position should be used. AnyStreet will always use the provided position.

        Default Value: DividedStreetOnly

Return type:

dict

Returns:

Response Syntax

{
    'Connections': [
        {
            'Distance': 123,
            'From': 'string',
            'RestDuration': 123,
            'To': 'string',
            'TravelDuration': 123,
            'WaitDuration': 123
        },
    ],
    'Distance': 123,
    'Duration': 123,
    'ImpedingWaypoints': [
        {
            'FailedConstraints': [
                {
                    'Constraint': 'AccessHours'|'AppointmentTime'|'Before'|'Heading'|'ServiceDuration'|'SideOfStreet',
                    'Reason': 'string'
                },
            ],
            'Id': 'string',
            'Position': [
                123.0,
            ]
        },
    ],
    'OptimizedWaypoints': [
        {
            'ArrivalTime': 'string',
            'DepartureTime': 'string',
            'Id': 'string',
            'Position': [
                123.0,
            ]
        },
    ],
    'PricingBucket': 'string',
    'TimeBreakdown': {
        'RestDuration': 123,
        'ServiceDuration': 123,
        'TravelDuration': 123,
        'WaitDuration': 123
    }
}

Response Structure

• (dict) –

  • Connections (list) –

    Details about the connection from one waypoint to the next, within the optimized sequence.

    • (dict) –

      This contains information such as distance and duration from one waypoint to the next waypoint in the sequence.

      • Distance (integer) –

        Distance of the step.

      • From (string) –

        contains the ID of the starting waypoint in this connection.

      • RestDuration (integer) –

        Resting time before the driver can continue driving.

      • To (string) –

        Contains the ID of the ending waypoint in this connection.

      • TravelDuration (integer) –

        Total duration.

        Unit: seconds

      • WaitDuration (integer) –

        Duration of a wait step.

        Unit: seconds

  • Distance (integer) –

    Overall distance to travel the whole sequence.

  • Duration (integer) –

    Overall duration to travel the whole sequence.

    Unit: seconds

  • ImpedingWaypoints (list) –

    Returns waypoints that caused the optimization problem to fail, and the constraints that were unsatisfied leading to the failure.

    • (dict) –

      The impeding waypoint.

      • FailedConstraints (list) –

        Failed constraints for an impeding waypoint.

        • (dict) –

          The failed constraint.

          • Constraint (string) –

            The failed constraint.

          • Reason (string) –

            Reason for the failed constraint.

      • Id (string) –

        The waypoint Id.

      • Position (list) –

        Position defined as [longitude, latitude].

        • (float) –

  • OptimizedWaypoints (list) –

    Waypoints in the order of the optimized sequence.

    • (dict) –

      The optimized waypoint.

      • ArrivalTime (string) –

        Estimated 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

      • DepartureTime (string) –

        Estimated 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

      • Id (string) –

        The waypoint Id.

      • Position (list) –

        Position defined as [longitude, latitude].

        • (float) –

  • PricingBucket (string) –

    The pricing bucket for which the query is charged at.

  • TimeBreakdown (dict) –

    Time breakdown for the sequence.

    • RestDuration (integer) –

      Resting phase of the cycle.

      Unit: seconds

    • ServiceDuration (integer) –

      Service time spent at the destination. At an appointment, the service time should be the appointment duration.

      Unit: seconds

    • TravelDuration (integer) –

      Traveling phase of the cycle.

      Unit: seconds

    • WaitDuration (integer) –

      Waiting phase of the cycle.

      Unit: seconds

Exceptions

• LocationServiceRoutesV2.Client.exceptions.InternalServerException

• LocationServiceRoutesV2.Client.exceptions.AccessDeniedException

• LocationServiceRoutesV2.Client.exceptions.ValidationException

• LocationServiceRoutesV2.Client.exceptions.ThrottlingException