:doc:`LocationService <../../location>` / Client / calculate_route

***************
calculate_route
***************



.. py:method:: LocationService.Client.calculate_route(**kwargs)

  

  

  .. warning::

    

    This operation is no longer current and may be deprecated in the future. We recommend you upgrade to `CalculateRoutes </location/latest/APIReference/API_CalculateRoutes.html>`__ or `CalculateIsolines </location/latest/APIReference/API_CalculateIsolines.html>`__ unless you require Grab data.

     

    
    * ``CalculateRoute`` is part of a previous Amazon Location Service Routes API (version 1) which has been superseded by a more intuitive, powerful, and complete API (version 2).
     
    * The version 2 ``CalculateRoutes`` operation gives better results for point-to-point routing, while the version 2 ``CalculateIsolines`` operation adds support for calculating service areas and travel time envelopes.
     
    * If you are using an Amazon Web Services SDK or the Amazon Web Services CLI, note that the Routes API version 2 is found under ``geo-routes`` or ``geo_routes``, not under ``location``.
     
    * Since Grab is not yet fully supported in Routes API version 2, we recommend you continue using API version 1 when using Grab.
    

    

   

  `Calculates a route <https://docs.aws.amazon.com/location/previous/developerguide/calculate-route.html>`__ given the following required parameters: ``DeparturePosition`` and ``DestinationPosition``. Requires that you first `create a route calculator resource <https://docs.aws.amazon.com/location-routes/latest/APIReference/API_CreateRouteCalculator.html>`__.

   

  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 <https://docs.aws.amazon.com/location/previous/developerguide/departure-time.html>`__ using either ``DepartureTime`` or ``DepartNow``. This calculates a route based on predictive traffic data at the given time. 

  .. note::

    You can't specify both ``DepartureTime`` and ``DepartNow`` in a single request. Specifying both parameters returns a validation error.

  
   
  * `Specifying a travel mode <https://docs.aws.amazon.com/location/previous/developerguide/travel-mode.html>`__ using TravelMode sets the transportation mode used to calculate the routes. This also lets you specify additional route preferences in ``CarModeOptions`` if traveling by ``Car``, or ``TruckModeOptions`` if traveling by ``Truck``. 

  .. note::

    If you specify ``walking`` for the travel mode and your data provider is Esri, the start and destination must be within 40km.

  
  

  

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/location-2020-11-19/CalculateRoute>`_  


  **Request Syntax**
  ::

    response = client.calculate_route(
        CalculatorName='string',
        DeparturePosition=[
            123.0,
        ],
        DestinationPosition=[
            123.0,
        ],
        WaypointPositions=[
            [
                123.0,
            ],
        ],
        TravelMode='Car'|'Truck'|'Walking'|'Bicycle'|'Motorcycle',
        DepartureTime=datetime(2015, 1, 1),
        DepartNow=True|False,
        DistanceUnit='Kilometers'|'Miles',
        IncludeLegGeometry=True|False,
        CarModeOptions={
            'AvoidFerries': True|False,
            'AvoidTolls': True|False
        },
        TruckModeOptions={
            'AvoidFerries': True|False,
            'AvoidTolls': True|False,
            'Dimensions': {
                'Length': 123.0,
                'Height': 123.0,
                'Width': 123.0,
                'Unit': 'Meters'|'Feet'
            },
            'Weight': {
                'Total': 123.0,
                'Unit': 'Kilograms'|'Pounds'
            }
        },
        ArrivalTime=datetime(2015, 1, 1),
        OptimizeFor='FastestRoute'|'ShortestRoute',
        Key='string'
    )
    
  :type CalculatorName: string
  :param CalculatorName: **[REQUIRED]** 

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

    

  
  :type DeparturePosition: list
  :param DeparturePosition: **[REQUIRED]** 

    The start position for the route. Defined in `World Geodetic System (WGS 84) <https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84>`__ format: ``[longitude, latitude]``.

     

    
    * For example, ``[-123.115, 49.285]``
    

     

    .. note::

      

      If you specify a departure that's not located on a road, Amazon Location `moves the position to the nearest road <https://docs.aws.amazon.com/location/previous/developerguide/snap-to-nearby-road.html>`__. 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]``

    

  
    - *(float) --* 

    

  :type DestinationPosition: list
  :param DestinationPosition: **[REQUIRED]** 

    The finish position for the route. Defined in `World Geodetic System (WGS 84) <https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84>`__ format: ``[longitude, latitude]``.

     

    
    * For example, ``[-122.339, 47.615]``
    

     

    .. note::

      

      If you specify a destination that's not located on a road, Amazon Location `moves the position to the nearest road <https://docs.aws.amazon.com/location/previous/developerguide/snap-to-nearby-road.html>`__.

      

     

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

    

  
    - *(float) --* 

    

  :type WaypointPositions: list
  :param 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]]``
    

     

    .. note::

      

      If you specify a waypoint position that's not located on a road, Amazon Location `moves the position to the nearest road <https://docs.aws.amazon.com/location/previous/developerguide/snap-to-nearby-road.html>`__.

       

      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]``

    

  
    - *(list) --* 

    
      - *(float) --* 

      
  

  :type TravelMode: string
  :param TravelMode: 

    Specifies the mode of transport when calculating a route. Used in estimating the speed of travel and road compatibility. You can choose ``Car``, ``Truck``, ``Walking``, ``Bicycle`` or ``Motorcycle`` as options for the ``TravelMode``.

     

    .. note::

      

      ``Bicycle`` and ``Motorcycle`` are only valid when using Grab as a data provider, and only within Southeast Asia.

       

      ``Truck`` is not available for Grab.

       

      For more details on the using Grab for routing, including areas of coverage, see `GrabMaps <https://docs.aws.amazon.com/location/previous/developerguide/grab.html>`__ in the *Amazon Location Service Developer Guide*.

      

     

    The ``TravelMode`` you specify also 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``

    

  
  :type DepartureTime: datetime
  :param DepartureTime: 

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

     

    
    * In `ISO 8601 <https://www.iso.org/iso-8601-date-and-time-format.html>`__ format: ``YYYY-MM-DDThh:mm:ss.sssZ``. For example, ``2020–07-2T12:15:20.000Z+01:00``
    

    

  
  :type DepartNow: boolean
  :param 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``

    

  
  :type DistanceUnit: string
  :param DistanceUnit: 

    Set the unit system to specify the distance.

     

    Default Value: ``Kilometers``

    

  
  :type IncludeLegGeometry: boolean
  :param 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``

    

  
  :type CarModeOptions: dict
  :param CarModeOptions: 

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

     

    Requirements: ``TravelMode`` must be specified as ``Car``.

    

  
    - **AvoidFerries** *(boolean) --* 

      Avoids ferries when calculating routes.

       

      Default Value: ``false``

       

      Valid Values: ``false`` | ``true``

      

    
    - **AvoidTolls** *(boolean) --* 

      Avoids tolls when calculating routes.

       

      Default Value: ``false``

       

      Valid Values: ``false`` | ``true``

      

    
  
  :type TruckModeOptions: dict
  :param 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``.

    

  
    - **AvoidFerries** *(boolean) --* 

      Avoids ferries when calculating routes.

       

      Default Value: ``false``

       

      Valid Values: ``false`` | ``true``

      

    
    - **AvoidTolls** *(boolean) --* 

      Avoids tolls when calculating routes.

       

      Default Value: ``false``

       

      Valid Values: ``false`` | ``true``

      

    
    - **Dimensions** *(dict) --* 

      Specifies the truck's dimension specifications including length, height, width, and unit of measurement. Used to avoid roads that can't support the truck's dimensions.

      

    
      - **Length** *(float) --* 

        The length of the truck.

         

        
        * For example, ``15.5``.
        

         

        .. note::

          

          For routes calculated with a HERE resource, this value must be between 0 and 300 meters.

          

        

      
      - **Height** *(float) --* 

        The height of the truck.

         

        
        * For example, ``4.5``.
        

         

        .. note::

          

          For routes calculated with a HERE resource, this value must be between 0 and 50 meters.

          

        

      
      - **Width** *(float) --* 

        The width of the truck.

         

        
        * For example, ``4.5``.
        

         

        .. note::

          

          For routes calculated with a HERE resource, this value must be between 0 and 50 meters.

          

        

      
      - **Unit** *(string) --* 

        Specifies the unit of measurement for the truck dimensions.

         

        Default Value: ``Meters``

        

      
    
    - **Weight** *(dict) --* 

      Specifies the truck's weight specifications including total weight and unit of measurement. Used to avoid roads that can't support the truck's weight.

      

    
      - **Total** *(float) --* 

        The total weight of the truck.

         

        
        * For example, ``3500``.
        

        

      
      - **Unit** *(string) --* 

        The unit of measurement to use for the truck weight.

         

        Default Value: ``Kilograms``

        

      
    
  
  :type ArrivalTime: datetime
  :param ArrivalTime: 

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

     

    .. note::

      

      ArrivalTime is not supported Esri.

      

    

  
  :type OptimizeFor: string
  :param OptimizeFor: 

    Specifies the distance to optimize for when calculating a route.

    

  
  :type Key: string
  :param Key: 

    The optional `API key <https://docs.aws.amazon.com/location/previous/developerguide/using-apikeys.html>`__ to authorize the request.

    

  
  
  :rtype: dict
  :returns: 
    
    **Response Syntax**

    
    ::

      {
          'Legs': [
              {
                  'StartPosition': [
                      123.0,
                  ],
                  'EndPosition': [
                      123.0,
                  ],
                  'Distance': 123.0,
                  'DurationSeconds': 123.0,
                  'Geometry': {
                      'LineString': [
                          [
                              123.0,
                          ],
                      ]
                  },
                  'Steps': [
                      {
                          'StartPosition': [
                              123.0,
                          ],
                          'EndPosition': [
                              123.0,
                          ],
                          'Distance': 123.0,
                          'DurationSeconds': 123.0,
                          'GeometryOffset': 123
                      },
                  ]
              },
          ],
          'Summary': {
              'RouteBBox': [
                  123.0,
              ],
              'DataSource': 'string',
              'Distance': 123.0,
              'DurationSeconds': 123.0,
              'DistanceUnit': 'Kilometers'|'Miles'
          }
      }
      
    **Response Structure**

    

    - *(dict) --* 

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

      
      

      - **Legs** *(list) --* 

        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 <https://docs.aws.amazon.com/location/previous/developerguide/snap-to-nearby-road.html>`__:

         

        
        * 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.
        

        
        

        - *(dict) --* 

          Contains the calculated route's details for each path between a pair of positions. 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 <https://docs.aws.amazon.com/location/previous/developerguide/snap-to-nearby-road.html>`__:

           

          
          * 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.
          

          
          

          - **StartPosition** *(list) --* 

            The starting position of the leg. Follows the format ``[longitude,latitude]``.

             

            .. note::

              

              If the ``StartPosition`` isn't located on a road, it's `snapped to a nearby road <https://docs.aws.amazon.com/location/previous/developerguide/snap-to-nearby-road.html>`__.

              

            
            

            - *(float) --* 
        
          

          - **EndPosition** *(list) --* 

            The terminating position of the leg. Follows the format ``[longitude,latitude]``.

             

            .. note::

              

              If the ``EndPosition`` isn't located on a road, it's `snapped to a nearby road <https://docs.aws.amazon.com/location/previous/developerguide/nap-to-nearby-road.html>`__.

              

            
            

            - *(float) --* 
        
          

          - **Distance** *(float) --* 

            The distance between the leg's ``StartPosition`` and ``EndPosition`` along a calculated route.

             

            
            * The default measurement is ``Kilometers`` unless the request specifies a ``DistanceUnit`` of ``Miles``.
            

            
          

          - **DurationSeconds** *(float) --* 

            The estimated travel time between the leg's ``StartPosition`` and ``EndPosition``. The travel mode and departure time that you specify in the request determines the calculated time.

            
          

          - **Geometry** *(dict) --* 

            Contains the calculated route's path as a linestring geometry.

            
            

            - **LineString** *(list) --* 

              An ordered list of positions used to plot a route on a map.

               

              The first position is closest to the start position for the leg, and the last position is the closest to the end position for the leg.

               

              
              * For example, ``[[-123.117, 49.284],[-123.115, 49.285],[-123.115, 49.285]]``
              

              
              

              - *(list) --* 
                

                - *(float) --* 
            
          
        
          

          - **Steps** *(list) --* 

            Contains a list of steps, which represent subsections of a leg. Each step provides instructions for how to move to the next step in the leg such as the step's start position, end position, travel distance, travel duration, and geometry offset.

            
            

            - *(dict) --* 

              Represents an element of a leg within a route. A step contains instructions for how to move to the next step in the leg.

              
              

              - **StartPosition** *(list) --* 

                The starting position of a step. If the position is the first step in the leg, this position is the same as the start position of the leg.

                
                

                - *(float) --* 
            
              

              - **EndPosition** *(list) --* 

                The end position of a step. If the position the last step in the leg, this position is the same as the end position of the leg.

                
                

                - *(float) --* 
            
              

              - **Distance** *(float) --* 

                The travel distance between the step's ``StartPosition`` and ``EndPosition``.

                
              

              - **DurationSeconds** *(float) --* 

                The estimated travel time, in seconds, from the step's ``StartPosition`` to the ``EndPosition``. . The travel mode and departure time that you specify in the request determines the calculated time.

                
              

              - **GeometryOffset** *(integer) --* 

                Represents the start position, or index, in a sequence of steps within the leg's line string geometry. For example, the index of the first step in a leg geometry is ``0``.

                 

                Included in the response for queries that set ``IncludeLegGeometry`` to ``True``.

                
          
        
      
    
      

      - **Summary** *(dict) --* 

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

        
        

        - **RouteBBox** *(list) --* 

          Specifies a geographical box surrounding a route. Used to zoom into a route when displaying it in a map. For example, ``[min x, min y, max x, max y]``.

           

          The first 2 ``bbox`` parameters describe the lower southwest corner:

           

          
          * The first ``bbox`` position is the X coordinate or longitude of the lower southwest corner.
           
          * The second ``bbox`` position is the Y coordinate or latitude of the lower southwest corner.
          

           

          The next 2 ``bbox`` parameters describe the upper northeast corner:

           

          
          * The third ``bbox`` position is the X coordinate, or longitude of the upper northeast corner.
           
          * The fourth ``bbox`` position is the Y coordinate, or latitude of the upper northeast corner.
          

          
          

          - *(float) --* 
      
        

        - **DataSource** *(string) --* 

          The data provider of traffic and road network data used to calculate the route. Indicates one of the available providers:

           

          
          * ``Esri``
           
          * ``Grab``
           
          * ``Here``
          

           

          For more information about data providers, see `Amazon Location Service data providers <https://docs.aws.amazon.com/location/previous/developerguide/what-is-data-provider.html>`__.

          
        

        - **Distance** *(float) --* 

          The total distance covered by the route. The sum of the distance travelled between every stop on the route.

           

          .. note::

            

            If Esri is the data source for the route calculator, the route distance can’t be greater than 400 km. If the route exceeds 400 km, the response is a ``400 RoutesValidationException`` error.

            

          
        

        - **DurationSeconds** *(float) --* 

          The total travel time for the route measured in seconds. The sum of the travel time between every stop on the route.

          
        

        - **DistanceUnit** *(string) --* 

          The unit of measurement for route distances.

          
    
  
  **Exceptions**
  
  *   :py:class:`LocationService.Client.exceptions.InternalServerException`

  
  *   :py:class:`LocationService.Client.exceptions.ResourceNotFoundException`

  
  *   :py:class:`LocationService.Client.exceptions.AccessDeniedException`

  
  *   :py:class:`LocationService.Client.exceptions.ValidationException`

  
  *   :py:class:`LocationService.Client.exceptions.ThrottlingException`

  