Reports API

The Reports API provides traffic analytics, violation statistics, and report management.

Overview

Procedure	Type	Auth	Description
reports.getAnalytics	Query	Yes	Get comprehensive analytics dashboard
reports.getReports	Query	Yes	Get list of generated reports

Procedures

reports.getAnalytics

Get comprehensive analytics data including seatbelt violations and traffic events.

Type: Query Auth Required: Yes

Response

{
  seatbeltViolations: {
    total: number;           // Total violation count
    trend: number;           // % change from previous month
    avgPerDay: number;       // Average violations per day
    complianceRate: number;  // Compliance percentage (0-100)
    criticalHours: string[]; // Peak violation hours (e.g., ["08:00-08:59", "17:00-17:59"])
    topLocations: Array<{
      name: string;
      violations: number;
    }>;
  };
  trafficEvents: {
    total: number;           // Total event count
    trend: number;           // % change from previous month
    avgPerDay: number;       // Average events per day
    peakHour: string;        // Peak traffic hour (e.g., "08:00-08:59")
    eventTypes: Array<{
      type: string;
      count: number;
      percentage: number;
    }>;
  };
}

Example

curl -X GET "https://api.itms.solutions/trpc/reports.getAnalytics" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response Example

{
  "result": {
    "data": {
      "json": {
        "seatbeltViolations": {
          "total": 1250,
          "trend": -5.2,
          "avgPerDay": 41.7,
          "complianceRate": 87,
          "criticalHours": ["08:00-08:59", "17:00-17:59"],
          "topLocations": [
            { "name": "Main Intersection", "violations": 342 },
            { "name": "Highway Checkpoint", "violations": 256 },
            { "name": "Downtown Junction", "violations": 198 }
          ]
        },
        "trafficEvents": {
          "total": 8540,
          "trend": 12.3,
          "avgPerDay": 284.7,
          "peakHour": "08:00-08:59",
          "eventTypes": [
            { "type": "Speed Violation", "count": 3420, "percentage": 40.0 },
            { "type": "Red Light", "count": 2135, "percentage": 25.0 },
            { "type": "Lane Violation", "count": 1707, "percentage": 20.0 }
          ]
        }
      }
    }
  }
}

Errors

Code	Description
UNAUTHORIZED	Not authenticated
INTERNAL_SERVER_ERROR	Failed to fetch analytics data

---

reports.getReports

Get a list of all generated reports with creator information.

Type: Query Auth Required: Yes

Response

Array<{
  id: string;
  name: string;
  description: string | null;
  type: string;              // Report type (e.g., "DAILY", "WEEKLY", "MONTHLY")
  status: string;            // Status (e.g., "COMPLETED", "PENDING", "FAILED")
  filePath: string | null;
  userId: string;
  createdAt: string;
  updatedAt: string;
  createdBy: {
    id: string;
    firstName: string;
    lastName: string;
    email: string;
  } | null;
  downloadUrl: string;       // URL to download the report
  size: number;              // File size in bytes
  format: string;            // File format (e.g., "PDF")
}>

Example

curl -X GET "https://api.itms.solutions/trpc/reports.getReports" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response Example

{
  "result": {
    "data": {
      "json": [
        {
          "id": "report-001",
          "name": "Weekly Traffic Summary",
          "description": "Traffic analysis for week 45",
          "type": "WEEKLY",
          "status": "COMPLETED",
          "filePath": "/reports/weekly-45.pdf",
          "userId": "admin-001",
          "createdAt": "2024-11-15T10:30:00.000Z",
          "updatedAt": "2024-11-15T10:35:00.000Z",
          "createdBy": {
            "id": "admin-001",
            "firstName": "System",
            "lastName": "Administrator",
            "email": "admin@itms.solutions"
          },
          "downloadUrl": "https://storage.itms.solutions/reports/report-001",
          "size": 0,
          "format": "PDF"
        }
      ]
    }
  }
}

Analytics Calculations

Trend Calculation

Trend values compare the current month to the previous month:

trend = ((current - previous) / previous) * 100

• Positive trend: Increase in events/violations
• Negative trend: Decrease in events/violations

Compliance Rate

complianceRate = ((totalTraffic - violations) / totalTraffic) * 100

Critical Hours

Hours with the highest violation counts in the last 30 days, sorted by frequency.

Event Types

Event types are grouped by violationType and include:

• Count of events
• Percentage of total

Report Types

Type	Description
DAILY	Daily summary report
WEEKLY	Weekly analysis report
MONTHLY	Monthly comprehensive report
CUSTOM	Custom date range report
INCIDENT	Specific incident report

Report Status

Status	Description
PENDING	Report generation in progress
COMPLETED	Report ready for download
FAILED	Report generation failed
EXPIRED	Report file expired/deleted