forecast_geofence_events ¶

def forecast_geofence_events(
    self,
    collection_name: "capo_location.types.resource_name.ResourceName",
    device_state: "capo_location.types.forecast_geofence_events_device_state.ForecastGeofenceEventsDeviceState",
    *,
    config_overrides: Optional[LocationClientConfig] = None,
    time_horizon_minutes: Optional[float] = None,
    distance_unit: Optional[
        "capo_location.types.distance_unit.DistanceUnit"
    ] = None,
    speed_unit: Optional["capo_location.types.speed_unit.SpeedUnit"] = None,
    next_token: Optional["capo_location.types.large_token.LargeToken"] = None,
    max_results: Optional[int] = None,
) -> "capo_location.types.forecast_geofence_events_response.ForecastGeofenceEventsResponse":
    """<p>This action forecasts future geofence events that are likely to occur within a specified time horizon if a device continues moving at its current speed. Each forecasted event is associated with a geofence from a provided geofence collection. A forecast event can have one of the following states:</p> <p> <code>ENTER</code>: The device position is outside the referenced geofence, but the device may cross into the geofence during the forecasting time horizon if it maintains its current speed.</p> <p> <code>EXIT</code>: The device position is inside the referenced geofence, but the device may leave the geofence during the forecasted time horizon if the device maintains it's current speed.</p> <p> <code>IDLE</code>:The device is inside the geofence, and it will remain inside the geofence through the end of the time horizon if the device maintains it's current speed.</p> <note> <p>Heading direction is not considered in the current version. The API takes a conservative approach and includes events that can occur for any heading.</p> </note>

    Args:
        collection_name: <p>The name of the geofence collection.</p>
        device_state: <p>Represents the device's state, including its current position and speed. When speed is omitted, this API performs a <i>containment check</i>. The <i>containment check</i> operation returns <code>IDLE</code> events for geofences where the device is currently inside of, but no other events.</p>
        time_horizon_minutes: <p>The forward-looking time window for forecasting, specified in minutes. The API only returns events that are predicted to occur within this time horizon. When no value is specified, this API performs a <i>containment check</i>. The <i>containment check</i> operation returns <code>IDLE</code> events for geofences where the device is currently inside of, but no other events.</p>
        distance_unit: <p>The distance unit used for the <code>NearestDistance</code> property returned in a forecasted event. The measurement system must match for <code>DistanceUnit</code> and <code>SpeedUnit</code>; if <code>Kilometers</code> is specified for <code>DistanceUnit</code>, then <code>SpeedUnit</code> must be <code>KilometersPerHour</code>. </p> <p>Default Value: <code>Kilometers</code> </p>
        speed_unit: <p>The speed unit for the device captured by the device state. The measurement system must match for <code>DistanceUnit</code> and <code>SpeedUnit</code>; if <code>Kilometers</code> is specified for <code>DistanceUnit</code>, then <code>SpeedUnit</code> must be <code>KilometersPerHour</code>.</p> <p>Default Value: <code>KilometersPerHour</code>.</p>
        next_token: <p>The pagination token specifying which page of results to return in the response. If no token is provided, the default page is the first page.</p> <p>Default value: <code>null</code> </p>
        max_results: <p>An optional limit for the number of resources returned in a single call.</p> <p>Default value: <code>20</code> </p>

    Raises:
        capo_location.errors.access_denied_exception.AccessDeniedException: <p>The request was denied because of insufficient access or permissions. Check with an administrator to verify your permissions.</p>
        capo_location.errors.internal_server_exception.InternalServerException: <p>The request has failed to process because of an unknown server error, exception, or failure.</p>
        capo_location.errors.resource_not_found_exception.ResourceNotFoundException: <p>The resource that you've entered was not found in your AWS account.</p>
        capo_location.errors.throttling_exception.ThrottlingException: <p>The request was denied because of request throttling.</p>
        capo_location.errors.validation_exception.ValidationException: <p>The input failed to meet the constraints specified by the AWS service. </p>
        capo_location.errors.UnknownServiceError: The service returned an error code this client does not model.
    """

    def _handler(
        req: "OperationRequest[capo_location.types.forecast_geofence_events_request.ForecastGeofenceEventsRequest]",
    ) -> OperationResponse[
        "capo_location.types.forecast_geofence_events_response.ForecastGeofenceEventsResponse"
    ]:
        import capo_location._operations.location_service.forecast_geofence_events

        output, http_response = (
            capo_location._operations.location_service.forecast_geofence_events.forecast_geofence_events(
                req.options, req.input
            )
        )
        return OperationResponse(output=output, response=http_response)

    def _redact_input(
        input_: "capo_location.types.forecast_geofence_events_request.ForecastGeofenceEventsRequest",
    ) -> dict[str, Any]:
        import capo_location.types.forecast_geofence_events_request

        return (
            capo_location.types.forecast_geofence_events_request.redact_sensitive(
                input_
            )
        )

    def _redact_output(
        output: "capo_location.types.forecast_geofence_events_response.ForecastGeofenceEventsResponse",
    ) -> dict[str, Any]:
        import capo_location.types.forecast_geofence_events_response

        return (
            capo_location.types.forecast_geofence_events_response.redact_sensitive(
                output
            )
        )

    interceptors_, options_ = self.operation_options(
        config_overrides,
        OperationLogging(
            "ForecastGeofenceEvents",
            redact_input=_redact_input,
            redact_output=_redact_output,
        ),
    )
    input_: capo_location.types.forecast_geofence_events_request.ForecastGeofenceEventsRequest = {
        "collection_name": collection_name,
        "device_state": device_state,
    }
    if time_horizon_minutes is not None:
        input_["time_horizon_minutes"] = time_horizon_minutes
    if distance_unit is not None:
        input_["distance_unit"] = distance_unit
    if speed_unit is not None:
        input_["speed_unit"] = speed_unit
    if next_token is not None:
        input_["next_token"] = next_token
    if max_results is not None:
        input_["max_results"] = max_results

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