Traffic Events API (Pending)

Migration Pending

This API is pending migration to Cloudflare Workers.

The Traffic Events API handles real-time traffic data, violations, and event processing.

Planned Procedures

Procedure	Type	Description
trafficEvents.getAll	Query	Get paginated events
trafficEvents.getById	Query	Get event details
trafficEvents.create	Mutation	Create new event
trafficEvents.getByLocation	Query	Get events at location
trafficEvents.getByDateRange	Query	Get events in time range
trafficEvents.getStats	Query	Get event statistics
trafficEvents.getRecent	Query	Get recent events
trafficEvents.subscribe	Subscription	Real-time event stream

Data Model

Traffic Event

interface TrafficEvent {
  id: string;
  eventType: EventType;
  violationType?: ViolationType;
  sensorId: string;
  locationId?: string;
  locationName?: string;
  vehiclePlate?: string;
  vehicleType?: VehicleType;
  speed?: number;
  speedLimit?: number;
  confidence: number;
  imageUrl?: string;
  videoUrl?: string;
  metadata?: Record<string, any>;
  processed: boolean;
  createdAt: Date;
  updatedAt: Date;
}

Event Type

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

Violation Type

enum ViolationType {
  SPEEDING = "SPEEDING",
  RED_LIGHT = "RED_LIGHT",
  WRONG_WAY = "WRONG_WAY",
  NO_SEATBELT = "NO_SEATBELT",
  PHONE_USE = "PHONE_USE",
  LANE_VIOLATION = "LANE_VIOLATION",
  ILLEGAL_PARKING = "ILLEGAL_PARKING",
  NO_HELMET = "NO_HELMET"
}

Vehicle Type

enum VehicleType {
  CAR = "CAR",
  MOTORCYCLE = "MOTORCYCLE",
  TRUCK = "TRUCK",
  BUS = "BUS",
  BICYCLE = "BICYCLE",
  PEDESTRIAN = "PEDESTRIAN",
  UNKNOWN = "UNKNOWN"
}

Planned Input Schemas

Query Events

{
  skip?: number;
  take?: number;                   // Max 100
  eventType?: EventType;
  violationType?: ViolationType;
  sensorId?: string;
  locationId?: string;
  vehiclePlate?: string;
  startDate?: Date;
  endDate?: Date;
  minConfidence?: number;          // 0-100
  processed?: boolean;
  sortBy?: "createdAt" | "confidence" | "speed";
  sortOrder?: "asc" | "desc";
}

Create Event

{
  eventType: EventType;
  violationType?: ViolationType;
  sensorId: string;
  locationId?: string;
  vehiclePlate?: string;
  vehicleType?: VehicleType;
  speed?: number;
  speedLimit?: number;
  confidence: number;              // 0-100
  imageBase64?: string;
  metadata?: Record<string, any>;
}

Expected Responses

Get Events

{
  "events": [
    {
      "id": "evt-001",
      "eventType": "TRAFFIC_VIOLATION",
      "violationType": "SPEEDING",
      "sensorId": "sensor-001",
      "locationName": "Main Street Intersection",
      "vehiclePlate": "KZ 123 ABC",
      "vehicleType": "CAR",
      "speed": 85,
      "speedLimit": 60,
      "confidence": 98.5,
      "imageUrl": "https://storage.itms.solutions/events/evt-001.jpg",
      "processed": true,
      "createdAt": "2024-11-15T14:30:00.000Z"
    }
  ],
  "total": 15420,
  "pageCount": 155
}

Get Statistics

{
  "totalEvents": 15420,
  "byType": {
    "TRAFFIC_VIOLATION": 8540,
    "SEATBELT_VIOLATION": 3200,
    "VEHICLE_DETECTION": 2500,
    "SPEED_DETECTION": 1180
  },
  "byHour": [
    { "hour": 8, "count": 1250 },
    { "hour": 9, "count": 980 },
    { "hour": 17, "count": 1340 }
  ],
  "avgConfidence": 94.2,
  "processingRate": 99.8
}

Real-time Events

WebSocket Connection

const ws = new WebSocket('wss://api.itms.solutions/events');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('New event:', data);
};

Event Stream Format

{
  "type": "NEW_EVENT",
  "data": {
    "id": "evt-002",
    "eventType": "SEATBELT_VIOLATION",
    "sensorId": "sensor-003",
    "confidence": 95.2,
    "timestamp": "2024-11-15T14:31:00.000Z"
  }
}

Migration Challenges

High Volume Data

• Millions of events per month
• Need efficient pagination
• Time-based partitioning required

Real-time Requirements

• Current: RabbitMQ message queue
• Target: Cloudflare Queues + Durable Objects

Image Processing

• Event images stored in R2
• Need efficient upload pipeline
• Consider Cloudflare Images for thumbnails

D1 Schema

CREATE TABLE events (
  id TEXT PRIMARY KEY,
  eventType TEXT NOT NULL,
  violationType TEXT,
  sensorId TEXT NOT NULL,
  locationId TEXT,
  locationName TEXT,
  vehiclePlate TEXT,
  vehicleType TEXT,
  speed REAL,
  speedLimit REAL,
  confidence REAL NOT NULL,
  imageUrl TEXT,
  videoUrl TEXT,
  metadata TEXT,
  processed INTEGER DEFAULT 0,
  createdAt TEXT NOT NULL,
  updatedAt TEXT NOT NULL,
  FOREIGN KEY (sensorId) REFERENCES Sensor(id)
);

CREATE INDEX idx_events_type ON events(eventType);
CREATE INDEX idx_events_sensor ON events(sensorId);
CREATE INDEX idx_events_created ON events(createdAt);
CREATE INDEX idx_events_plate ON events(vehiclePlate);

Related APIs

• Sensors - Sensors generating events
• Reports - Event analytics and reports
• Locations - Event locations
• Incidents - Incident creation from events