calculate_routes ¶

def calculate_routes(
    self,
    destination: "capo_geo_routes.types.position.Position",
    origin: "capo_geo_routes.types.position.Position",
    *,
    config_overrides: Optional[GeoRoutesClientConfig] = None,
    allow: Optional[
        "capo_geo_routes.types.route_allow_options.RouteAllowOptions"
    ] = None,
    arrival_time: Optional[
        "capo_geo_routes.types.timestamp_with_timezone_offset.TimestampWithTimezoneOffset"
    ] = None,
    avoid: Optional[
        "capo_geo_routes.types.route_avoidance_options.RouteAvoidanceOptions"
    ] = None,
    depart_now: Optional[
        "capo_geo_routes.types.sensitive_boolean.SensitiveBoolean"
    ] = None,
    departure_time: Optional[
        "capo_geo_routes.types.timestamp_with_timezone_offset.TimestampWithTimezoneOffset"
    ] = None,
    destination_options: Optional[
        "capo_geo_routes.types.route_destination_options.RouteDestinationOptions"
    ] = None,
    driver: Optional[
        "capo_geo_routes.types.route_driver_options.RouteDriverOptions"
    ] = None,
    exclude: Optional[
        "capo_geo_routes.types.route_exclusion_options.RouteExclusionOptions"
    ] = None,
    instructions_measurement_system: Optional[
        "capo_geo_routes.types.measurement_system.MeasurementSystem"
    ] = None,
    key: Optional["capo_geo_routes.types.api_key.ApiKey"] = None,
    languages: Optional[
        "capo_geo_routes.types.language_tag_list.LanguageTagList"
    ] = None,
    leg_additional_features: Optional[
        "capo_geo_routes.types.route_leg_additional_feature_list.RouteLegAdditionalFeatureList"
    ] = None,
    leg_geometry_format: Optional[
        "capo_geo_routes.types.geometry_format.GeometryFormat"
    ] = None,
    max_alternatives: Optional[int] = None,
    optimize_routing_for: Optional[
        "capo_geo_routes.types.routing_objective.RoutingObjective"
    ] = None,
    origin_options: Optional[
        "capo_geo_routes.types.route_origin_options.RouteOriginOptions"
    ] = None,
    span_additional_features: Optional[
        "capo_geo_routes.types.route_span_additional_feature_list.RouteSpanAdditionalFeatureList"
    ] = None,
    tolls: Optional[
        "capo_geo_routes.types.route_toll_options.RouteTollOptions"
    ] = None,
    traffic: Optional[
        "capo_geo_routes.types.route_traffic_options.RouteTrafficOptions"
    ] = None,
    travel_mode: Optional[
        "capo_geo_routes.types.route_travel_mode.RouteTravelMode"
    ] = None,
    travel_mode_options: Optional[
        "capo_geo_routes.types.route_travel_mode_options.RouteTravelModeOptions"
    ] = None,
    travel_step_type: Optional[
        "capo_geo_routes.types.route_travel_step_type.RouteTravelStepType"
    ] = None,
    waypoints: Optional[
        "capo_geo_routes.types.route_waypoint_list.RouteWaypointList"
    ] = None,
) -> "capo_geo_routes.types.calculate_routes_response.CalculateRoutesResponse":
    """<p> <code>CalculateRoutes</code> computes routes given the following required parameters: <code>Origin</code> and <code>Destination</code>.</p> <p>For more information, see <a href="https://docs.aws.amazon.com/location/latest/developerguide/calculate-routes.html">Calculate routes</a> in the <i>Amazon Location Service Developer Guide</i>.</p>

    Args:
        allow: <p> Features that are allowed while calculating a route. Not supported in <code>ap-southeast-1</code> and <code>ap-southeast-5</code> regions for <a href="https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html">GrabMaps</a> customers. </p>
        arrival_time: <p> Time of arrival at the destination. Not supported in <code>ap-southeast-1</code> and <code>ap-southeast-5</code> regions for <a href="https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html">GrabMaps</a> customers. </p> <p>Time format:<code>YYYY-MM-DDThh:mm:ss.sssZ | YYYY-MM-DDThh:mm:ss.sss+hh:mm</code> </p> <p>Examples:</p> <p> <code>2020-04-22T17:57:24Z</code> </p> <p> <code>2020-04-22T17:57:24+02:00</code> </p>
        avoid: <p> 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. For <a href="https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html">GrabMaps</a> customers, <code>ap-southeast-1</code> and <code>ap-southeast-5</code> regions support only <code>ControlledAccessHighways</code>, <code>Ferries</code>, and <code>TollRoads</code> </p>
        depart_now: <p>Uses the current time as the time of departure.</p>
        departure_time: <p>Time of departure from the origin.</p> <p>Time format:<code>YYYY-MM-DDThh:mm:ss.sssZ | YYYY-MM-DDThh:mm:ss.sss+hh:mm</code> </p> <p>Examples:</p> <p> <code>2020-04-22T17:57:24Z</code> </p> <p> <code>2020-04-22T17:57:24+02:00</code> </p>
        destination: <p>The final position for the route. In the World Geodetic System (WGS 84) format: <code>[longitude, latitude]</code>.</p>
        destination_options: <p> Destination related options. Not supported in <code>ap-southeast-1</code> and <code>ap-southeast-5</code> regions for <a href="https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html">GrabMaps</a> customers. </p>
        driver: <p> Driver related options. Not supported in <code>ap-southeast-1</code> and <code>ap-southeast-5</code> regions for <a href="https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html">GrabMaps</a> customers. </p>
        exclude: <p> Features to be strictly excluded while calculating the route. Not supported in <code>ap-southeast-1</code> and <code>ap-southeast-5</code> regions for <a href="https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html">GrabMaps</a> customers. </p>
        instructions_measurement_system: <p>Measurement system to be used for instructions within steps in the response.</p>
        key: <p>Optional: The API key to be used for authorization. Either an API key or valid SigV4 signature must be provided when making a request. </p>
        languages: <p> List of languages for instructions within steps in the response. Not supported in <code>ap-southeast-1</code> and <code>ap-southeast-5</code> regions for <a href="https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html">GrabMaps</a> customers. </p> <note> <p>Instructions in the requested language are returned only if they are available.</p> </note>
        leg_additional_features: <p> A list of optional additional parameters such as timezone that can be requested for each result. For <a href="https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html">GrabMaps</a> customers, <code>ap-southeast-1</code> and <code>ap-southeast-5</code> regions support only <code>PassThroughWaypoints</code>, <code>Summary</code>, and <code>TravelStepInstructions</code> </p> <ul> <li> <p> <code>Elevation</code>: Retrieves the elevation information for each location.</p> </li> <li> <p> <code>Incidents</code>: Provides information on traffic incidents along the route.</p> </li> <li> <p> <code>PassThroughWaypoints</code>: Indicates waypoints that are passed through without stopping.</p> </li> <li> <p> <code>Summary</code>: Returns a summary of the route, including distance and duration.</p> </li> <li> <p> <code>Tolls</code>: Supplies toll cost information along the route.</p> </li> <li> <p> <code>TravelStepInstructions</code>: Provides step-by-step instructions for travel along the route.</p> </li> <li> <p> <code>TruckRoadTypes</code>: Returns information about road types suitable for trucks.</p> </li> <li> <p> <code>TypicalDuration</code>: Gives typical travel duration based on historical data.</p> </li> <li> <p> <code>Zones</code>: Specifies the time zone information for each waypoint.</p> </li> </ul>
        leg_geometry_format: <p>Specifies the format of the geometry returned for each leg of the route. You can choose between two different geometry encoding formats.</p> <p> <code>FlexiblePolyline</code>: A compact and precise encoding format for the leg geometry. For more information on the format, see the GitHub repository for <a href="https://github.com/aws-geospatial/polyline">https://github.com/aws-geospatial/polyline</a>.</p> <p> <code>Simple</code>: A less compact encoding, which is easier to decode but may be less precise and result in larger payloads.</p>
        max_alternatives: <p>Maximum number of alternative routes to be provided in the response, if available. For <a href="https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html">GrabMaps</a> customers, <code>ap-southeast-1</code> and <code>ap-southeast-5</code> regions support only up to 3 alternative routes. </p>
        optimize_routing_for: <p>Controls the trade-off between achieving the shortest travel time (<code>FastestRoute</code>) and achieving the shortest physical distance ((<code>ShortestRoute</code>) when calculating each route in the matrix.</p> <p>Default value: <code>FastestRoute</code> </p>
        origin: <p>The start position for the route in World Geodetic System (WGS 84) format: [longitude, latitude].</p>
        origin_options: <p> Specifies how the origin point should be matched to the road network and any routing constraints that apply when the traveler is departing the origin. Not supported in <code>ap-southeast-1</code> and <code>ap-southeast-5</code> regions for <a href="https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html">GrabMaps</a> customers. </p>
        span_additional_features: <p> A list of optional features such as <code>SpeedLimit</code> that can be requested for a Span. A span is a section of a Leg for which the requested features have the same values. Not supported in <code>ap-southeast-1</code> and <code>ap-southeast-5</code> regions for <a href="https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html">GrabMaps</a> customers. </p>
        tolls: <p> Toll related options. Not supported in <code>ap-southeast-1</code> and <code>ap-southeast-5</code> regions for <a href="https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html">GrabMaps</a> customers. </p>
        traffic: <p> Traffic related options. Not supported in <code>ap-southeast-1</code> and <code>ap-southeast-5</code> regions for <a href="https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html">GrabMaps</a> customers. </p>
        travel_mode: <p> Specifies the mode of transport when calculating a route. Used in estimating the speed of travel and road compatibility. For <a href="https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html">GrabMaps</a> customers, <code>ap-southeast-1</code> and <code>ap-southeast-5</code> regions support only <code>Car</code>, <code>Pedestrian</code>, and <code>Scooter</code> values. </p> <p>Default value: <code>Car</code> </p>
        travel_mode_options: <p> Travel mode related options for the provided travel mode. For <a href="https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html">GrabMaps</a> customers, <code>ap-southeast-1</code> and <code>ap-southeast-5</code> regions support only <code>Car</code> and <code>Pedestrian</code> travel mode options. </p>
        travel_step_type: <p>Type of step returned by the response. <code>Default</code> provides basic steps intended for web based applications. <code>TurnByTurn</code> provides detailed instructions with more granularity intended for a turn based navigation system. For <a href="https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html">GrabMaps</a> customers, <code>ap-southeast-1</code> and <code>ap-southeast-5</code> regions <code>Default</code> does not return any steps. </p>
        waypoints: <p> List of waypoints between the Origin and Destination. For <a href="https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html">GrabMaps</a> customers, <code>ap-southeast-1</code> and <code>ap-southeast-5</code> regions max length is <code>100</code>. </p> <p>Max length: <code>23</code> </p>

    Raises:
        capo_geo_routes.errors.access_denied_exception.AccessDeniedException: <p>You don't have sufficient access to perform this action.</p>
        capo_geo_routes.errors.internal_server_exception.InternalServerException: <p>The request processing has failed because of an unknown error, exception or failure.</p>
        capo_geo_routes.errors.throttling_exception.ThrottlingException: <p>The request was denied due to request throttling.</p>
        capo_geo_routes.errors.validation_exception.ValidationException: <p>The input fails to satisfy the constraints specified by an AWS service.</p>
        capo_geo_routes.errors.UnknownServiceError: The service returned an error code this client does not model.
    """

    def _handler(
        req: "OperationRequest[capo_geo_routes.types.calculate_routes_request.CalculateRoutesRequest]",
    ) -> OperationResponse[
        "capo_geo_routes.types.calculate_routes_response.CalculateRoutesResponse"
    ]:
        import capo_geo_routes._operations.routes_service.calculate_routes

        output, http_response = (
            capo_geo_routes._operations.routes_service.calculate_routes.calculate_routes(
                req.options, req.input
            )
        )
        return OperationResponse(output=output, response=http_response)

    def _redact_input(
        input_: "capo_geo_routes.types.calculate_routes_request.CalculateRoutesRequest",
    ) -> dict[str, Any]:
        import capo_geo_routes.types.calculate_routes_request

        return capo_geo_routes.types.calculate_routes_request.redact_sensitive(
            input_
        )

    def _redact_output(
        output: "capo_geo_routes.types.calculate_routes_response.CalculateRoutesResponse",
    ) -> dict[str, Any]:
        import capo_geo_routes.types.calculate_routes_response

        return capo_geo_routes.types.calculate_routes_response.redact_sensitive(
            output
        )

    interceptors_, options_ = self.operation_options(
        config_overrides,
        OperationLogging(
            "CalculateRoutes",
            redact_input=_redact_input,
            redact_output=_redact_output,
        ),
    )
    input_: capo_geo_routes.types.calculate_routes_request.CalculateRoutesRequest = {
        "destination": destination,
        "origin": origin,
    }
    if allow is not None:
        input_["allow"] = allow
    if arrival_time is not None:
        input_["arrival_time"] = arrival_time
    if avoid is not None:
        input_["avoid"] = avoid
    if depart_now is not None:
        input_["depart_now"] = depart_now
    if departure_time is not None:
        input_["departure_time"] = departure_time
    if destination_options is not None:
        input_["destination_options"] = destination_options
    if driver is not None:
        input_["driver"] = driver
    if exclude is not None:
        input_["exclude"] = exclude
    if instructions_measurement_system is not None:
        input_["instructions_measurement_system"] = instructions_measurement_system
    if key is not None:
        input_["key"] = key
    if languages is not None:
        input_["languages"] = languages
    if leg_additional_features is not None:
        input_["leg_additional_features"] = leg_additional_features
    if leg_geometry_format is not None:
        input_["leg_geometry_format"] = leg_geometry_format
    if max_alternatives is not None:
        input_["max_alternatives"] = max_alternatives
    if optimize_routing_for is not None:
        input_["optimize_routing_for"] = optimize_routing_for
    if origin_options is not None:
        input_["origin_options"] = origin_options
    if span_additional_features is not None:
        input_["span_additional_features"] = span_additional_features
    if tolls is not None:
        input_["tolls"] = tolls
    if traffic is not None:
        input_["traffic"] = traffic
    if travel_mode is not None:
        input_["travel_mode"] = travel_mode
    if travel_mode_options is not None:
        input_["travel_mode_options"] = travel_mode_options
    if travel_step_type is not None:
        input_["travel_step_type"] = travel_step_type
    if waypoints is not None:
        input_["waypoints"] = waypoints

    response = execute_pipeline(
        OperationRequest(input=input_, options=options_),
        handler=_handler,
        interceptors=list(interceptors_),
    )
    response.response.close()
    return response.output