Event

Real-time Event (Subscription)

This connection provides real-time notifications for events detected by the AI using WebSocket. The events contain information about the detected objects and their associated confidence scores. Once connected, the WebSocket will send real-time events as they occur.

Note: Please check the Authentication to get the service_id and token

Endpoint:

ws(s)://yourserver.com/apiserver/events/realtime/:service_id/:task_id?token=xxxxx

{
  "task_id": 1,
  "event_id": 2001,
  "event_name": "vehicle_detected",
  "event_description": "A vehicle was detected.",
  "timestamp": "2023-03-13T04:02:42Z",
  "image_url": "https://example.com/event_images/1.jpg",
  "video_url": "https://example.com/event_videos/1.mp4"
  "detected_objects": [
    {
      "object_id": "101",
      "object_name": "car",
      "coordinates": [0.1, 0.2, 0.3, 0.4],
      "confidence_score": 0.8
      "warning": true
    }
  ]
}

Response Fields

Field	Description	Type
task_id	The task ID related to the event.	integer
event_id	The unique identifier for the event.	integer
event_name	The name of the event.	string
event_description	A brief description of the event.	string
timestamp	The timestamp when the event occurred.	string
image_url	The URL of the event's image snapshot. Note: need to add auth_token to get image e.g. https://example.com/event_images/1.jpg?auth_token={token}	string
video_url	The URL of the event's video clip. Note: need to add auth_token to get video e.g. https://example.com/event_videos/1.jpg?auth_token={token}	string
license_plate	The detected license_plate of the event	string
detected_objects	An array of detected object information, including object_id, object_name, coordinates, confidence_score, and warning. Details see below	array

detected_objects

Field	Description	Type
object_id	The object ID.	string
object_name	The object name.	string
coordinates	The bbox normalized [cx, cy, w, h] Note: need to multiply the display image width and height if want to draw on the image.	array
confidence_score	The confidence score between 0~1	float
warning	The object is in warning state of not	boolean

---

Event History

The Event History API allows users to query past events detected by the AI detection system for a specific task. Users can filter the events based on a time range and event name, enabling them to analyze and review historical data efficiently.

Endpoint: GET /events/history

Payload:

Field	Description	Data Type	Require
start_time	Start time of the time range in ISO 8601 format (e.g., "2023-03-01T00:00:00").	time	optional
end_time	End time of the time range in ISO 8601 format (e.g., "2023-03-28T23:59:59").	time	optional
event_name	Filter by event name (e.g., "vehicle_detected").	string	optional
task_id	Filter by task ID.	string	optional
event_id	Filter by event ID.	string	optional
location_id	Filter by location ID.	string	optional
camera_id	Filter by camera ID.	string	optional
scenario_id	Filter by scenario ID.	string	optional
ids	Fetch specific ids.	string	optional
offset	The starting position of the query results.	integer	optional, default: 0
limit	The maximum number of query results. Maximum 10000	integer	optional, default: 100

Example Request:

GET /events/history?ids=1&start_time=2023-03-01T00:00:00&end_time=2023-03-28T23:59:59&event_name=vehicle_detected&task_id=1&offset=0&limit=10

Response

The response will be a JSON object containing an array of events that match the specified filters. Each event object will include the following information:

Example

[
    {
      "task_id": 1,
      "event_id": 1,
      "event_name": "vehicle_detected",
      "event_description": "A vehicle was detected.",
      "timestamp": "2023-06-13T04:02:42Z",
      "image_url": "https://example.com/event_images/1.jpg",
      "video_url": "https://example.com/event_videos/1.mp4",
      "detected_objects": [
        {
          "object_id": "101",
          "object_name": "car",
          "coordinates": [0.1, 0.2, 0.3, 0.4],
          "confidence_score": 0.8,
          "warning": false
        }
      ],
      "location_id": 1,
      "scenario_id": 103,
      "camera_id": 1
    }
]

#Response Fields

Field	Description	Type
task_id	The task ID related to the event.	integer
event_id	The unique identifier for the event.	integer
event_name	The name of the event.	string
event_description	A brief description of the event.	string
timestamp	The timestamp when the event occurred.	string
image_url	The URL of the event's image snapshot. Note: need to add auth_token to get image e.g. https://example.com/event_images/1.jpg?auth_token={token}	string
video_url	The URL of the event's video clip. Note: need to add auth_token to get video e.g. https://example.com/event_videos/1.jpg?auth_token={token}	string
license_plate	The detected license_plate of the event	string
detected_objects	An array of detected object information, including object_id, object_name, coordinates, confidence_score, and warning. Details see below	array
location_id	The location ID related to the event.	integer
scenario_id	The scenario ID related to the event.	integer
camera_id	The camera ID related to the event.	integer

#detected_objects

Field	Description	Type
object_id	The object ID.	string
object_name	The object name.	string
coordinates	The bbox normalized [cx, cy, w, h] Note: need to multiply the display image width and height if want to draw on the image.	array
confidence_score	The confidence score between 0~1	float
warning	The object is in warning state of not	boolean

---

Event Detail

This API retrieves detailed information about a specific event, including the event name, event description.

Endpoint: GET /events/types/:event_id

Parameters:

Parameter	Description	Type	Required
event_id	The unique identifier for the event.	integer	Yes

Example Request:

GET /events/types/1

Response:

{
    "id": 1,
    "name": "Person detected in zone",
    "description": "Person detected entering the forbidden area."
}

Response Fields:

Field	Description	Type
name	The name of the event.	string
description	A brief description of the event.	string