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