Introduction

In Eagle Eye API V3, the /events API retrieves the detected events in the system. In general, events in a security system are any occurrence detected by the system using an algorithm or sensor. As an example, motion events are movements in a camera image.

Event types

The following table describes the event types that are currently supported by the /events API:

Event Type	Name	Description
`een.deviceCloudStatusUpdateEvent.v1`	Device status	A new event of this type is created when a device's status changes. The event represents the span of time the device stays in the given state and a null `endTimestamp` indicates it was still in the given state when the event was retrieved
`een.motionDetectionEvent.v1`	Motion Detection	A new event of this type is created when there is a motion in front of the camera. The event represents the span of time for which the motion happened and a null `endTimestamp` indicates that the motion was still ongoing when the event was retrieved
`een.motionInRegionDetectionEvent.v1.yaml`	Motion In ROI Detection	A new event of this type is created when a motion is detected in a specific region of interest.
`een.lprPlateReadEvent.v1`	License plate recognition	A new event of this type is created when the camera captures a license plate of a passing vehicle. It represents a single point in time.
`een.loiterDetectionEvent.v1`	Loitering Detection	A new event of this type is created when an object remains in the scene longer than the specified time in the `minimumDwellTimeSec`attribute.
`een.tamperDetectionEvent.v1`	Tampering event	Used to generate an alert when someone is trying to block the camera's view or the image is greatly altered.
`een.objectLineCrossEvent.v1`	Line Crossing Detection	A new event of this type is created when an object crosses the line specified in `line:` attribute.
`een.objectIntrusionEvent.v1`	Intrusion Detection	A new event of this type is created when an object enters into the area specified in the `area:` attribute.

Note: More events are coming. Please stay tuned.

Retrieving information on a camera's events

This section describes the steps you need to follow to retrieve event information for a camera using the /event API.

Prerequisites

Login to your account and receive an access token.
Get our Base URL from the client setting API
Using the Cameras API retrieve a list of the connected cameras to the end user.
Pick the camera ID that you want to check for events.

Procedure

Call the list /events endpoint.

Example:

curl --location '<base-URL>/api/v3.0/events?startTimestamp__gte=2023-05-19T11%3A30%3A15.418%2B00%3A00&endTimestamp__lte=2023-05-19T12%3A30%3A15.418%2B00%3A00&actor=camera%3A1004cb8c&pageSize=10&type__in=een.deviceCloudStatusUpdateEvent.v1&include=data.een.deviceCloudStatusUpdate.v1' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <access-token>'

📘
Note
The startTimestamp gte and endTimestamp lte should be in [ISO 8601 format.
For example: 2023-05-15T11:30:15.418%2B00:00

An example response of an /events GET request:

{
    "nextPageToken": "",
    "prevPageToken": "",
    "results": [
        {
            "type": "een.deviceCloudStatusUpdateEvent.v1",
            "id": "1004cb8c-2023-05-19T11:30:15.418Z-een.deviceCloudStatusUpdateEvent.v1",
            "startTimestamp": "2023-05-19T11:30:15.418+00:00",
            "endTimestamp": null,
            "span": true,
            "accountId": "00098540",
            "actorId": "1004cb8c",
            "actorAccountId": "00098540",
            "actorType": "camera",
            "creatorId": "een.systemHealth",
            "dataSchemas": [
                "data.een.deviceCloudStatusUpdate.v1"
            ],
            "data": [
                {
                    "type": "een.deviceCloudStatusUpdateEvent.v1",
                    "creatorId": "een.systemHealth",
                    "newStatus": {
                        "connectionStatus": "online"
                    }
                }
            ]
        }
    ],
    "totalSize": 1
}

📘
Note
Each event will have one or more dataSchemas associated with it. These dataSchemas provide additional information that can be requested with an event to gain more insight regarding an event. For instance, the following information can be available through dataSchemas:

Bounding boxes when an object is detected.

Event snapshot URL's for the event.

LPR data, such as license plate number, the bounding box of the license plate, and so on.

Additional information, such as upper body clothing color, people carrying backpack, and so on.

Users can request one or more dataSchemas with an event and based on whether the event has the dataSchemas, data will be returned.
Example:
If you include the type data.een.deviceCloudStatusUpdate.v1 in the include parameter of the API you will get the above result in the data field.
There are two more endpoints in the /events API:

api/v3.0/events:listFieldValues. This endpoint retrieves the types of event that are supported

api/v3.0/eventTypes?language=pg. This endpoint retrieves a description for each type of supported events.

Sample code

Here is a simple CLI tool that stores 10 images of the first 10 motion events following the start timestamp based on four inputs from the user. Images are stored in the c:/events/ folder.

Before you begin: Before running the code, make sure you have all the required (imported) libraries installed.

The four inputs are the following:

access token
Base_URL
Camera ID
Start timestamp

In the following example, the end timestamp is required in calling the /event endpoint, so the endTimestamp is calculated as 1 hour after the startTimestamp:

import requests
from dateutil.parser import parse
from dateutil.relativedelta import relativedelta
from urllib.parse import quote_plus
from datetime import timedelta
import time

BEARER = "Bearer "
EVENTS_DIR = "c:/events/"

def get_input(prompt):
    return input(prompt)

def get_data_from_api(session, url, headers):
    response = session.get(url, headers=headers)
    response.raise_for_status()
    return response.json()

def save_image_from_url(session, url, headers, file_path):
    retries = 5
    delay = 5
    for _ in range(retries):
        try:
            response = session.get(url, headers=headers, stream=True)
            print(response)
            response.raise_for_status()
            with open(file_path, 'wb') as out_file:
                out_file.write(response.content)
            return
        except requests.exceptions.HTTPError as err:
            if retries > 1:
                time.sleep(delay)  # wait before trying again
                retries -= 1
                continue
            else:
                raise err

def prepare_timestamps(start_timestamp_input):
    start_timestamp = parse(start_timestamp_input)
    start_timestamp_str = start_timestamp.isoformat().replace("+00:00", ".000%2B00:00")

    end_timestamp = start_timestamp + relativedelta(hours=1)
    end_timestamp_str = end_timestamp.isoformat().replace("+00:00", ".000%2B00:00")

    return start_timestamp_str, end_timestamp_str

def main():
    with requests.Session() as session:
        access_token = get_input("Enter Access Token: ")
        base_url = get_input("Enter Base URL: ")
        camera_id = get_input("Enter Camera ID: ")
        start_timestamp_input = get_input("Enter start timestamp (YYYY-MM-DDTHH:MM:SS.000Z): ")

        start_timestamp_str, end_timestamp_str = prepare_timestamps(start_timestamp_input)

        headers = {"Authorization": BEARER + access_token}
        url = f"https://{base_url}/api/v3.0/events?startTimestamp__gte={start_timestamp_str}&endTimestamp__lte={end_timestamp_str}&actor=camera:{camera_id}&pageSize=100"
        data = get_data_from_api(session, url, headers)

        motion_event_count = 0
        for result in data.get('results', []):
            if motion_event_count >= 10:
                break
            if result.get('creatorId') == "een.bridgeMotion":
                motion_start_timestamp = result.get('startTimestamp')
                if motion_start_timestamp:
                    timestamp_datetime = parse(motion_start_timestamp) + timedelta(milliseconds=500)
                    timestamp_str = timestamp_datetime.isoformat()
                    timestamp_url = quote_plus(timestamp_str)
                    image_url = f"https://{base_url}/api/v3.0/media/recordedImage.jpeg?deviceId={camera_id}&type=preview&timestamp__lt={timestamp_url}"
                    file_path = f"{EVENTS_DIR}{timestamp_str.replace(':', '-').replace('.', '-').replace('+', '-')}.jpg"
                    save_image_from_url(session, image_url, headers, file_path)
                    print(f"Saved image for timestamp {timestamp_str} to {file_path}")
                    motion_event_count += 1


if __name__ == "__main__":
    main()

📘
Note
The startTimestamp of the motion events represents the moment when the bridge first detected the motion. The best view of the moving object is not necessarily available at this moment. To have a better shot of the moving object, a 500 millisecond time delta is added to the startTimestamp in line 67. Depending on your use case, you can adjust this time.

📘
Tip
You can retrieve the main image of the event if you change the type=preview to type=main in line 70.

Events

Introduction

Event types

Retrieving information on a camera's events

Prerequisites

Procedure

📘
Note

📘
Note

Sample code

📘
Note

📘
Tip

Introduction

Event types

Retrieving information on a camera's events

Prerequisites

Procedure

📘Note

📘Note

Sample code

📘Note

📘Tip

📘
Note

📘
Note

📘
Note

📘
Tip