Events API

The Events API handles traffic events, violations, and event processing.

Overview

Procedure	Type	Auth	Description
events.ingest	Mutation	No*	Ingest event from sensor
events.getAll	Query	Yes	Get paginated events
events.getById	Query	Yes	Get event by ID
events.getRecent	Query	Yes	Get recent events
events.markAsProcessed	Mutation	Yes	Mark event processed
events.markAsArchived	Mutation	Yes	Archive event
events.delete	Mutation	Yes	Delete event
events.getStats	Query	Yes	Get event statistics
events.getEventTypes	Query	No	Get event types

*Requires sensor API key

Event Types

enum EventType {
  TRAFFIC_VIOLATION = "TRAFFIC_VIOLATION",
  SEATBELT_VIOLATION = "SEATBELT_VIOLATION",
  VEHICLE_DETECTION = "VEHICLE_DETECTION",
  SPEED_DETECTION = "SPEED_DETECTION",
  PLATE_RECOGNITION = "PLATE_RECOGNITION",
  INCIDENT = "INCIDENT"
}

Procedures

events.ingest

Public endpoint for sensors to submit events.

Type: Mutation Auth Required: Sensor API Key

Input

{
  apiKey: string;                    // Sensor API key
  eventType: EventType;              // Event type
  description?: string;
  location?: {
    latitude: number;
    longitude: number;
    address?: string;
  };
  metadata?: Record<string, any>;
  images?: string[];
  tags?: string[];
  violationType?: string;
  licensePlateNumber?: string;
  vehicleType?: string;
  vehicleSpeed?: number;
}

Response

{
  success: boolean;
  eventId: string;
}

Example

curl -X POST "https://api.itms.solutions/trpc/events.ingest" \
  -H "Content-Type: application/json" \
  -d '{
    "json": {
      "apiKey": "your-sensor-api-key",
      "eventType": "TRAFFIC_VIOLATION",
      "violationType": "SPEEDING",
      "licensePlateNumber": "KZ 123 ABC",
      "vehicleType": "CAR",
      "vehicleSpeed": 85,
      "location": {
        "latitude": 43.238949,
        "longitude": 76.945465,
        "address": "Main Street"
      }
    }
  }'

---

events.getAll

Get paginated events with filtering.

Type: Query Auth Required: Yes

Input

{
  eventType?: EventType;
  sensorId?: string;
  startDate?: string;         // ISO date string
  endDate?: string;           // ISO date string
  processed?: boolean;
  archived?: boolean;
  violationType?: string;
  licensePlateNumber?: string;
  vehicleType?: string;
  locationName?: string;
  skip?: number;              // Default: 0
  take?: number;              // Default: 50, max: 100
  sortBy?: "timestamp" | "createdAt" | "eventType" | "severity";
  sortOrder?: "asc" | "desc";
}

Response

{
  events: Array<{
    id: string;
    eventType: string;
    description: string | null;
    timestamp: string;
    sensorId: string | null;
    sensorName: string | null;
    processed: boolean;
    archived: boolean;
    violationType: string | null;
    licensePlateNumber: string | null;
    vehicleType: string | null;
    vehicleSpeed: number | null;
    locationName: string | null;
    severity: string | null;
    createdAt: string;
  }>;
  total: number;
  pageCount: number;
}

Example

curl -X GET "https://api.itms.solutions/trpc/events.getAll?input=%7B%22json%22%3A%7B%22eventType%22%3A%22TRAFFIC_VIOLATION%22%2C%22take%22%3A10%7D%7D" \
  -H "Authorization: Bearer YOUR_TOKEN"

---

events.getById

Get a single event by ID.

Type: Query Auth Required: Yes

Input

{
  id: string;
}

---

events.getRecent

Get the most recent events.

Type: Query Auth Required: Yes

Input

{
  limit?: number;            // Default: 10, max: 100
  eventType?: EventType;
}

---

events.markAsProcessed

Mark an event as processed.

Type: Mutation Auth Required: Yes

Input

{
  id: string;
}

Response

{
  success: boolean;
}

---

events.markAsArchived

Archive an event.

Type: Mutation Auth Required: Yes

Input

{
  id: string;
}

---

events.delete

Delete an event.

Type: Mutation Auth Required: Yes

Input

{
  id: string;
}

---

events.getStats

Get event statistics.

Type: Query Auth Required: Yes

Input

{
  startDate?: string;        // ISO date string
  endDate?: string;          // ISO date string
}

Response

{
  total: number;
  byType: Array<{
    eventType: string;
    count: number;
  }>;
  processed: number;
  unprocessed: number;
  archived: number;
  byViolationType: Array<{
    violationType: string;
    count: number;
  }>;
}

---

events.getEventTypes

Get available event types.

Type: Query Auth Required: No

Response

string[]  // Array of event type values

Violation Types

Common violation types:

Type	Description
SPEEDING	Speed limit exceeded
RED_LIGHT	Red light violation
WRONG_WAY	Driving wrong way
NO_SEATBELT	Seatbelt not worn
PHONE_USE	Phone use while driving
LANE_VIOLATION	Improper lane change
ILLEGAL_PARKING	Illegal parking

Event Lifecycle

┌──────────────┐
│   Created    │ ── Event ingested from sensor
└──────┬───────┘
       │
       ▼
┌──────────────┐
│  Unprocessed │ ── Awaiting review
└──────┬───────┘
       │
       ▼
┌──────────────┐
│  Processed   │ ── Reviewed and processed
└──────┬───────┘
       │
       ▼
┌──────────────┐
│   Archived   │ ── Historical record
└──────────────┘