LocationService / Client / forecast_geofence_events

forecast_geofence_events

LocationService.Client.forecast_geofence_events(**kwargs)

Evaluates device positions against geofence geometries from a given geofence collection. The event forecasts three states for which a device can be in relative to a geofence:

ENTER: If a device is outside of a geofence, but would breach the fence if the device is moving at its current speed within time horizon window.

EXIT: If a device is inside of a geofence, but would breach the fence if the device is moving at its current speed within time horizon window.

IDLE: If a device is inside of a geofence, and the device is not moving.

See also: AWS API Documentation

Request Syntax

response = client.forecast_geofence_events(
    CollectionName='string',
    DeviceState={
        'Position': [
            123.0,
        ],
        'Speed': 123.0
    },
    TimeHorizonMinutes=123.0,
    DistanceUnit='Kilometers'|'Miles',
    SpeedUnit='KilometersPerHour'|'MilesPerHour',
    NextToken='string',
    MaxResults=123
)

Parameters:

• CollectionName (string) –

  [REQUIRED]

  The name of the geofence collection.

• DeviceState (dict) –

  [REQUIRED]

  The device’s state, including current position and speed.

  • Position (list) – [REQUIRED]

    The device’s position.

    • (float) –

  • Speed (float) –

    The device’s speed.

• TimeHorizonMinutes (float) – Specifies the time horizon in minutes for the forecasted events.

• DistanceUnit (string) –

  The distance unit used for the NearestDistance property returned in a forecasted event. The measurement system must match for DistanceUnit and SpeedUnit; if Kilometers is specified for DistanceUnit, then SpeedUnit must be KilometersPerHour.

  Default Value: Kilometers

• SpeedUnit (string) –

  The speed unit for the device captured by the device state. The measurement system must match for DistanceUnit and SpeedUnit; if Kilometers is specified for DistanceUnit, then SpeedUnit must be KilometersPerHour.

  Default Value: KilometersPerHour.

• NextToken (string) –

  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.

  Default value: null

• MaxResults (integer) –

  An optional limit for the number of resources returned in a single call.

  Default value: 20

Return type:

dict

Returns:

Response Syntax

{
    'ForecastedEvents': [
        {
            'EventId': 'string',
            'GeofenceId': 'string',
            'IsDeviceInGeofence': True|False,
            'NearestDistance': 123.0,
            'EventType': 'ENTER'|'EXIT'|'IDLE',
            'ForecastedBreachTime': datetime(2015, 1, 1),
            'GeofenceProperties': {
                'string': 'string'
            }
        },
    ],
    'NextToken': 'string',
    'DistanceUnit': 'Kilometers'|'Miles',
    'SpeedUnit': 'KilometersPerHour'|'MilesPerHour'
}

Response Structure

• (dict) –

  • ForecastedEvents (list) –

    The list of forecasted events.

    • (dict) –

      A forecasted event represents a geofence event in relation to the requested device state, that may occur given the provided device state and time horizon.

      • EventId (string) –

        The forecasted event identifier.

      • GeofenceId (string) –

        The geofence identifier pertaining to the forecasted event.

      • IsDeviceInGeofence (boolean) –

        Indicates if the device is located within the geofence.

      • NearestDistance (float) –

        The closest distance from the device’s position to the geofence.

      • EventType (string) –

        The event type, forecasting three states for which a device can be in relative to a geofence:

        ENTER: If a device is outside of a geofence, but would breach the fence if the device is moving at its current speed within time horizon window.

        EXIT: If a device is inside of a geofence, but would breach the fence if the device is moving at its current speed within time horizon window.

        IDLE: If a device is inside of a geofence, and the device is not moving.

      • ForecastedBreachTime (datetime) –

        The forecasted time the device will breach the geofence in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ

      • GeofenceProperties (dict) –

        The geofence properties.

        • (string) –

          • (string) –

  • NextToken (string) –

    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.

  • DistanceUnit (string) –

    The distance unit for the forecasted events.

  • SpeedUnit (string) –

    The speed unit for the forecasted events.

Exceptions

• LocationService.Client.exceptions.InternalServerException

• LocationService.Client.exceptions.ResourceNotFoundException

• LocationService.Client.exceptions.AccessDeniedException

• LocationService.Client.exceptions.ValidationException

• LocationService.Client.exceptions.ThrottlingException