Skip to main content

Citizen Report Service

Service class for communicating with the external Citizen Ingestion API (FastAPI :8001) for crowdsourced traffic reports.

Overview​

The CitizenReportService handles all citizen-contributed data:

  • Report submissions with photo uploads
  • Report retrieval with advanced filtering
  • Status updates (pending Ò†’ verified/rejected)
  • Aggregated statistics
  • Direct integration with Stellio Context Broker
graph TD
    A[CitizenReportService] --> B[FastAPI :8001]
    A --> C[Stellio Context Broker]
    
    B --> D[Submit Reports]
    
    C --> E[Query Reports]
    C --> F[Get Report by ID]
    C --> G[Get Statistics]
    
    subgraph "Report Types"
        H[traffic_jam]
        I[accident]
        J[flood]
        K[road_damage]
        L[other]
    end

Configuration​

// External Citizen Ingestion API (FastAPI :8001)
const CITIZEN_API_URL = import.meta.env.VITE_CITIZEN_API_URL || 'http://localhost:8001';
const STELLIO_URL = import.meta.env.VITE_STELLIO_URL || 'http://localhost:8080';

Note: This service targets the separate FastAPI ingestion service, NOT the main Express backend (:5001).

API Methods​

submitReport​

Submit a new citizen report to the external API.

interface CitizenReportSubmission {
    userId: string;
    reportType: ReportType;
    description?: string;
    latitude: number;
    longitude: number;
    imageUrl: string;
    timestamp?: string;
}

async submitReport(submission: CitizenReportSubmission): Promise<{
    status: 'accepted' | 'rejected';
    message: string;
    reportId: string;
    processingStatus: string;
}>

queryReports​

Query citizen reports from Stellio Context Broker with optional filters.

interface CitizenReportFilters {
    reportType?: ReportType;
    status?: ReportStatus;
    aiVerified?: boolean;
    minConfidence?: number;
    hours?: number;
    userId?: string;
}

async queryReports(filters?: CitizenReportFilters): Promise<CitizenReport[]>

getReportById​

Get a specific report by its ID from Stellio.

async getReportById(reportId: string): Promise<CitizenReport | null>

getStats​

Get aggregated statistics about citizen reports.

interface CitizenReportStats {
    total: number;
    byType: Record<ReportType, number>;
    byStatus: Record<ReportStatus, number>;
    verified: number;
    unverified: number;
    avgConfidence: number;
    last24Hours: number;
}

async getStats(): Promise<CitizenReportStats>

Usage​

import { CitizenReportService } from './services/citizenReportService';

// Submit a new report
const result = await CitizenReportService.submitReport({
    userId: 'user123',
    reportType: 'accident',
    description: 'Minor collision at intersection',
    latitude: 10.762622,
    longitude: 106.660172,
    imageUrl: 'https://example.com/photo.jpg'
});

// Query verified accident reports
const accidents = await CitizenReportService.queryReports({
    reportType: 'accident',
    aiVerified: true,
    minConfidence: 0.8
});

// Get statistics
const stats = await CitizenReportService.getStats();
console.log(`${stats.total} total reports, ${stats.verified} verified`);

Report Types​

TypeDescription
traffic_jamTraffic congestion report
accidentRoad accident or collision
floodFlooding on road
road_damagePothole or road damage
otherOther traffic-related issue

Report Statuses​

StatusDescription
pending_verificationAwaiting AI verification
verifiedConfirmed by AI system
rejectedRejected as invalid

NGSI-LD Integration​

Reports are stored as CitizenObservation entities in Stellio:

{
    "id": "urn:ngsi-ld:CitizenObservation:abc123",
    "type": "CitizenObservation",
    "category": { "value": "accident" },
    "description": { "value": "Minor collision" },
    "location": {
        "value": {
            "type": "Point",
            "coordinates": [106.660172, 10.762622]
        }
    },
    "aiVerified": { "value": true },
    "aiConfidence": { "value": 0.92 },
    "reportedBy": { "object": "urn:ngsi-ld:User:user123" }
}

Dependencies​

  • axios@^1.4: HTTP client with multipart support
  • citizenReport types: TypeScript interfaces

See Also​