Incidents API (Pending)

Migration Pending

This API is pending migration to Cloudflare Workers.

The Incidents API manages traffic incidents, accident reports, and road conditions.

Planned Procedures

Procedure	Type	Description
incidents.getAll	Query	Get all incidents
incidents.getById	Query	Get incident details
incidents.create	Mutation	Report new incident
incidents.update	Mutation	Update incident status
incidents.resolve	Mutation	Mark incident resolved
incidents.addComment	Mutation	Add comment to incident
incidents.getActive	Query	Get active incidents
incidents.getByLocation	Query	Get incidents near location

Data Model

Incident

interface Incident {
  id: string;
  title: string;
  description: string;
  type: IncidentType;
  severity: IncidentSeverity;
  status: IncidentStatus;
  locationId?: string;
  coordinates: {
    latitude: number;
    longitude: number;
  };
  address?: string;
  reportedBy: string;
  assignedTo?: string;
  relatedEvents: string[];
  images: string[];
  comments: Comment[];
  resolvedAt?: Date;
  resolution?: string;
  createdAt: Date;
  updatedAt: Date;
}

Incident Type

enum IncidentType {
  ACCIDENT = "ACCIDENT",
  BREAKDOWN = "BREAKDOWN",
  ROAD_CLOSURE = "ROAD_CLOSURE",
  HAZARD = "HAZARD",
  WEATHER = "WEATHER",
  CONSTRUCTION = "CONSTRUCTION",
  CONGESTION = "CONGESTION",
  OTHER = "OTHER"
}

Incident Severity

enum IncidentSeverity {
  LOW = "LOW",         // Minor, no lane closure
  MEDIUM = "MEDIUM",   // Partial lane closure
  HIGH = "HIGH",       // Full lane closure
  CRITICAL = "CRITICAL" // Road closed, emergency
}

Incident Status

enum IncidentStatus {
  REPORTED = "REPORTED",
  CONFIRMED = "CONFIRMED",
  IN_PROGRESS = "IN_PROGRESS",
  RESOLVED = "RESOLVED",
  CANCELLED = "CANCELLED"
}

Comment

interface Comment {
  id: string;
  userId: string;
  userName: string;
  content: string;
  createdAt: Date;
}

Planned Input Schemas

Create Incident

{
  title: string;                   // Required, 5-200 chars
  description: string;             // Required, 10-2000 chars
  type: IncidentType;              // Required
  severity: IncidentSeverity;      // Required
  coordinates: {
    latitude: number;
    longitude: number;
  };
  address?: string;
  locationId?: string;
  relatedEvents?: string[];        // Event IDs
  images?: string[];               // Image URLs or base64
}

Update Incident

{
  id: string;                      // Required
  title?: string;
  description?: string;
  type?: IncidentType;
  severity?: IncidentSeverity;
  status?: IncidentStatus;
  assignedTo?: string;             // User ID
  address?: string;
}

Resolve Incident

{
  id: string;                      // Required
  resolution: string;              // Required, resolution notes
}

Query Incidents

{
  skip?: number;
  take?: number;
  type?: IncidentType;
  severity?: IncidentSeverity;
  status?: IncidentStatus;
  locationId?: string;
  reportedBy?: string;
  assignedTo?: string;
  startDate?: Date;
  endDate?: Date;
  bounds?: {
    north: number;
    south: number;
    east: number;
    west: number;
  };
}

Expected Responses

Get Incidents

{
  "incidents": [
    {
      "id": "inc-001",
      "title": "Multi-vehicle accident on Highway 1",
      "description": "Three vehicles involved in collision near KM 45",
      "type": "ACCIDENT",
      "severity": "HIGH",
      "status": "IN_PROGRESS",
      "coordinates": {
        "latitude": 43.238949,
        "longitude": 76.945465
      },
      "address": "Highway 1, KM 45, Almaty Region",
      "reportedBy": "user-001",
      "assignedTo": "user-002",
      "images": [
        "https://storage.itms.solutions/incidents/inc-001/1.jpg"
      ],
      "commentCount": 5,
      "createdAt": "2024-11-15T14:00:00.000Z"
    }
  ],
  "total": 42,
  "activeCount": 12
}

Get Active Incidents

{
  "incidents": [
    {
      "id": "inc-001",
      "title": "Multi-vehicle accident",
      "type": "ACCIDENT",
      "severity": "HIGH",
      "status": "IN_PROGRESS",
      "coordinates": { "latitude": 43.238, "longitude": 76.945 },
      "duration": "2h 30m",
      "affectedLanes": 2
    }
  ],
  "criticalCount": 2,
  "highCount": 5,
  "mediumCount": 3,
  "lowCount": 2
}

Use Cases

Incident Reporting

• Citizens report incidents via mobile app
• Operators confirm and manage incidents
• Automatic incident detection from sensors

Dispatching

• Assign incidents to field teams
• Track resolution progress
• Communication via comments

Public Information

• Display active incidents on map
• Provide traffic advisories
• Integration with navigation apps

Workflow

┌──────────────┐
│   REPORTED   │ ──── User/Sensor reports incident
└──────┬───────┘
       │
       ▼
┌──────────────┐
│  CONFIRMED   │ ──── Operator verifies incident
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ IN_PROGRESS  │ ──── Response team dispatched
└──────┬───────┘
       │
       ▼
┌──────────────┐
│   RESOLVED   │ ──── Incident cleared
└──────────────┘

D1 Schema

CREATE TABLE incidents (
  id TEXT PRIMARY KEY,
  title TEXT NOT NULL,
  description TEXT NOT NULL,
  type TEXT NOT NULL,
  severity TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'REPORTED',
  locationId TEXT,
  latitude REAL NOT NULL,
  longitude REAL NOT NULL,
  address TEXT,
  reportedBy TEXT NOT NULL,
  assignedTo TEXT,
  relatedEvents TEXT,
  images TEXT,
  resolution TEXT,
  resolvedAt TEXT,
  createdAt TEXT NOT NULL,
  updatedAt TEXT NOT NULL,
  FOREIGN KEY (reportedBy) REFERENCES User(id),
  FOREIGN KEY (assignedTo) REFERENCES User(id)
);

CREATE TABLE incident_comments (
  id TEXT PRIMARY KEY,
  incidentId TEXT NOT NULL,
  userId TEXT NOT NULL,
  content TEXT NOT NULL,
  createdAt TEXT NOT NULL,
  FOREIGN KEY (incidentId) REFERENCES incidents(id),
  FOREIGN KEY (userId) REFERENCES User(id)
);

CREATE INDEX idx_incidents_status ON incidents(status);
CREATE INDEX idx_incidents_severity ON incidents(severity);
CREATE INDEX idx_incidents_coords ON incidents(latitude, longitude);

Related APIs

• Locations - Incident locations
• Traffic Events - Related traffic events
• Users - Reporters and assignees