Stolen Vehicle Tracking API Developer Guide

Service Overview

The Stolen Vehicle Tracking Service is a telematics service that allows real-time vehicle location tracking and monitoring through the app when a vehicle is stolen.

Service Features

• Location tracking based on legal grounds (after police report verification)
• High-frequency real-time location tracking (seconds to tens of seconds interval)
• Independent tracking session management for app and call center
• Continuous tracking possible even when vehicle engine is OFF

Legal Requirements

• Location information protection laws apply in most countries
• Tracking permission allowed only in theft situations
• Customer prior consent mandatory
• Tracking logs stored for legal evidence purposes

Key Scenarios

Scenario 1: Theft Report and Tracking Start

API Flow by Entity:

📱 App (User):

1. Initiate Tracking: Start high-frequency tracking with police report
2. Real-time Monitoring: Receive live GPS updates via SSE
3. Status Check: Monitor vehicle battery and signal strength
4. Safety Zones: Set alerts for high-risk areas

🚗 Vehicle (TCU):

1. Command Reception: Receive tracking command and check system health
2. Live Transmission: Transmit coordinates every 10 seconds to the platform

🏢 Call Center:

1. Fleet Monitoring: Monitor all active theft sessions
2. Police Linkage: Coordinate recovery with local authorities
3. Engine Lockdown: Remotely disable engine to prevent movement

---

Scenario 2: Real-time Tracking Monitoring and Control

API Flow by Entity:

📱 App (User App):

1. Real-time Location Monitoring: Display real-time location on map via SSE
2. Tracking Status Check: Check battery, communication status
3. Tracking Analysis Check: Movement pattern, statistical analysis
4. Geofence Management: Set dangerous area alerts

🚗 Vehicle (TCU):

1. High-frequency Location Transmission: Continuously transmit location information every 10 seconds
2. GPS Signal Monitoring: Adjust location accuracy based on GPS reception status
3. Battery Status Transmission: Monitor battery threshold and transmit status
4. Geofence Detection: Send alerts when entering/exiting set areas

🏢 Call Center:

1. Multi-vehicle Monitoring: Simultaneously monitor multiple vehicle tracking sessions
2. Location Pattern Analysis: Movement route, speed pattern analysis
3. Tracking History Query: Analyze location history by time
4. Dangerous Area Management: Set geofences for high-crime areas

---

Scenario 3: Tracking End and Data Management

API Flow by Entity:

📱 App (User):

1. Stop Tracking: End tracking after recovery
2. Data Export: Generate reports for insurance/police
3. Unlock Engine: Restore vehicle functionality

🏢 Call Center:

1. Audit Analytics: Analyze recovery efficiency
2. History Review: Review full breadcrumb trail of the incident

---

Scenario 4: Emergency Situation Collaborative Response

API Flow by Entity:

🏢 Call Center:

1. Emergency Situation Assessment: Evaluate emergency situation severity based on tracking data
2. Immediate Police Linkage: Automatic police support request
3. Vehicle Engine Lock: Remote vehicle engine lock
4. Real-time Tracking Support: Provide real-time location for police tracking support

📱 App (User App):

1. Emergency Alert Reception: Immediately receive emergency situations via SSE
2. Real-time Location Sharing: Share real-time location information with police
3. Call Center Connection: Immediate call center connection in emergency situations
4. Vehicle Remote Control: Immediate vehicle engine lock in emergency situations

🚗 Vehicle (TCU):

1. Emergency Event Transmission: Immediately transmit emergency situations like GPS interference, low battery
2. Highest Priority Location: Transmit location information at highest frequency in emergency situations
3. Engine Lock Execution: Immediately execute Remote vehicle engine lock
4. Continuous Status Transmission: Continuously transmit status information until emergency situation resolution

Key Features

📱 Features to Implement in App

1. Tracking Initiation and Monitoring

• Live Stream: Connect to real-time GPS updates
• Start Session: Begin high-priority tracking
• Live Tracker: Dashboard of real-time movemement and status
• Event Alerts: Receive geofence and system warnings

2. Recovery and Reporting

• End Session: Cease tracking post-recovery
• Evidence Export: Generate reports for insurance/police
• History Audit: Review all past location data
• Analysis View: Pattern and statistical insights

---

🏢 Features to Implement in Call Center

1. Centralized tracking Operations

• Session Dashboard: Monitor all active tracking sessions
• Live Fleet View: Receive global location updates
• Incident Alerts: Process real-time system warnings
• Tracking Control: Manage session lifecycle and Manage session lifecycle

2. Recovery Control and Analysis

• Engine Lockdown: Remotely disable engine for theft prevention
• Function Restoration: Restore vehicle control after recovery
• Path Analytics: Deep-dive into movement routes
• Legal Compliance: Generate certified evidence logs

Sequence Diagram

Stolen Vehicle Tracking System Flow

API Endpoints

Refer to the Common API Specifications for headers, response codes, and error formats.

Stolen Vehicle Tracking

Stolen Vehicle Tracking Start

curl -X POST "https://api.ecarus.run/api/v1/security/vehicles/KMHSH81C7LU123456/stolen-tracking/start" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{
       "reason": "STOLEN_VEHICLE",
       "priority": "HIGH",
       "reportingInterval": 10,
       "gpsAccuracy": 10.0,
       "batteryThreshold": 20.0,
       "maxDuration": 86400,
       "emergencyContact": "+82-10-1234-5678",
       "policeReportNumber": "20240115-001234",
       "notes": "Vehicle stolen from parking lot"
     }'

Stolen Vehicle Tracking Stop

curl -X POST "https://api.ecarus.run/api/v1/security/vehicles/KMHSH81C7LU123456/stolen-tracking/stop" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{
       "sessionId": "sess_001",
       "reason": "VEHICLE_RECOVERED",
       "notes": "Vehicle found and recovered by police",
       "recoveryLocation": {
         "latitude": 37.5665,
         "longitude": 126.9780,
         "address": "Seoul, Jung-gu, Sejong-daero 110"
       }
     }'

Tracking Status Query

curl -X GET "https://api.ecarus.run/api/v1/security/vehicles/KMHSH81C7LU123456/stolen-tracking/status" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

Tracking History Query

curl -X GET "https://api.ecarus.run/api/v1/security/vehicles/KMHSH81C7LU123456/stolen-tracking/history?period=1h&limit=1000" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

Tracking Analysis Data Query

curl -X GET "https://api.ecarus.run/api/v1/security/vehicles/KMHSH81C7LU123456/stolen-tracking/analytics?period=24h" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

Tracking Data Export

curl -X POST "https://api.ecarus.run/api/v1/security/vehicles/KMHSH81C7LU123456/stolen-tracking/export" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{
       "sessionId": "sess_001",
       "format": "PDF",
       "includeDetails": true,
       "includeMap": true,
       "purpose": "INSURANCE_CLAIM",
       "emailRecipient": "user@example.com",
       "startTime": "2024-01-15T20:15:00Z",
       "endTime": "2024-01-15T21:30:00Z"
     }'

Geofence Management

Geofence Creation

curl -X POST "https://api.ecarus.run/api/v1/security/vehicles/KMHSH81C7LU123456/stolen-tracking/geofence" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Home Area",
       "type": "CIRCLE",
       "enabled": true,
       "coordinates": {
         "center": {
           "latitude": 37.5665,
           "longitude": 126.9780
         },
         "radius": 500
       },
       "schedule": {
         "active": true,
         "days": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY"],
         "startTime": "09:00",
         "endTime": "18:00"
       },
       "alerts": {
         "entry": true,
         "exit": true,
         "notificationChannels": ["PUSH", "EMAIL", "SMS"]
       }
     }'

Geofence List Query

curl -X GET "https://api.ecarus.run/api/v1/security/vehicles/KMHSH81C7LU123456/stolen-tracking/geofence" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

Real-time Event Reception (SSE)

Vehicle Location Real-time Update (SSE)

Note: Recommended to access via browser or use a dedicated SSE client

curl -N -H "Accept: text/event-stream" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     "https://api.ecarus.run/api/v1/security/vehicles/KMHSH81C7LU123456/stolen-tracking/location/stream"

Tracking Alert Reception (SSE)

Note: Recommended to access via browser or use a dedicated SSE client

curl -N -H "Accept: text/event-stream" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     "https://api.ecarus.run/api/v1/security/vehicles/KMHSH81C7LU123456/stolen-tracking/notifications"

Data Models

Stolen Vehicle Tracking Start Request

{
  "reason": "STOLEN_VEHICLE",
  "priority": "HIGH",
  "reportingInterval": 10,
  "gpsAccuracy": 10.0,
  "batteryThreshold": 20.0,
  "maxDuration": 86400,
  "emergencyContact": "+82-10-1234-5678",
  "policeReportNumber": "20240115-001234",
  "notes": "Vehicle stolen from parking lot"
}

Stolen Vehicle Tracking Start Response

{
  "vin": "KMHSH81C7LU123456",
  "sessionId": "sess_001",
  "status": "ACTIVE",
  "startTime": "2026-03-11T14:30:00Z",
  "trackingMode": "AGGRESSIVE",
  "reportingInterval": 10,
  "maxDuration": 86400
}

Stolen Vehicle Tracking Stop Request

{
  "sessionId": "sess_001",
  "reason": "VEHICLE_RECOVERED",
  "notes": "Vehicle found and recovered by police",
  "recoveryLocation": {
    "latitude": 37.5665,
    "longitude": 126.9780,
    "address": "Seoul, Jung-gu, Sejong-daero 110"
  }
}

Stolen Vehicle Tracking Stop Response

{
  "vin": "KMHSH81C7LU123456",
  "sessionId": "sess_001",
  "status": "STOPPED",
  "stopTime": "2026-03-11T18:30:00Z",
  "totalDuration": 14400,
  "totalDistance": 15.7,
  "locationCount": 480
}

Tracking Status Response

{
  "vin": "KMHSH81C7LU123456",
  "sessionId": "sess_001",
  "status": "ACTIVE",
  "startTime": "2026-03-11T14:30:00Z",
  "duration": 600,
  "trackingMode": "AGGRESSIVE",
  "reportingInterval": 10,
  "currentLocation": {
    "latitude": 37.5665,
    "longitude": 126.9780,
    "address": "Seoul, Gangnam-gu, Teheran-ro",
    "timestamp": "2026-03-11T14:45:00Z",
    "accuracy": 5.0,
    "speed": 25.5,
    "heading": 180.0
  },
  "vehicleStatus": {
    "batteryLevel": 85,
    "signalStrength": -75,
    "gnssStatus": "NORMAL",
    "networkStatus": "CONNECTED",
    "ignitionStatus": "OFF"
  },
  "trackingStats": {
    "totalDistance": 2.3,
    "averageSpeed": 23.9,
    "maxSpeed": 35.2,
    "locationCount": 60
  }
}

Tracking History Response

{
  "vin": "KMHSH81C7LU123456",
  "sessionId": "sess_001",
  "period": "1h",
  "locations": [
    {
      "latitude": 37.5665,
      "longitude": 126.9780,
      "timestamp": "2026-03-11T14:45:00Z",
      "speed": 25.5,
      "heading": 180.0,
      "accuracy": 5.0
    },
    {
      "latitude": 37.5660,
      "longitude": 126.9775,
      "timestamp": "2026-03-11T14:44:30Z",
      "speed": 22.3,
      "heading": 175.0,
      "accuracy": 4.8
    }
  ],
  "total": 120,
  "trackingStats": {
    "totalDistance": 15.7,
    "averageSpeed": 23.9,
    "maxSpeed": 45.2,
    "trackingDuration": 3600,
    "locationCount": 120
  }
}

Tracking Analysis Response

{
  "vin": "KMHSH81C7LU123456",
  "sessionId": "sess_001",
  "period": "24h",
  "analytics": {
    "summary": {
      "totalDistance": 45.2,
      "averageSpeed": 28.5,
      "maxSpeed": 65.3,
      "trackingDuration": 86400,
      "locationCount": 2880
    },
    "speedAnalysis": {
      "idleTime": 7200,
      "lowSpeedTime": 14400,
      "normalSpeedTime": 43200,
      "highSpeedTime": 21600
    },
    "locationAnalysis": {
      "urbanAreas": 65.5,
      "highways": 25.3,
      "ruralAreas": 9.2
    },
    "timeAnalysis": {
      "daytimeTracking": 43200,
      "nighttimeTracking": 43200,
      "peakHours": 10800
    }
  }
}

Tracking Data Export Request

{
  "sessionId": "sess_001",
  "format": "PDF",
  "includeDetails": true,
  "includeMap": true,
  "purpose": "INSURANCE_CLAIM",
  "emailRecipient": "user@example.com",
  "startTime": "2024-01-15T20:15:00Z",
  "endTime": "2024-01-15T21:30:00Z"
}

Tracking Data Export Response

{
  "vin": "KMHSH81C7LU123456",
  "sessionId": "sess_001",
  "exportId": "EXP-20260311-001",
  "status": "PROCESSING",
  "format": "PDF",
  "estimatedCompletion": "2026-03-11T18:45:00Z"
}

Geofence Creation Request

{
  "name": "Home Area",
  "type": "CIRCLE",
  "enabled": true,
  "coordinates": {
    "center": {
      "latitude": 37.5665,
      "longitude": 126.9780
    },
    "radius": 500
  },
  "schedule": {
    "active": true,
    "days": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY"],
    "startTime": "09:00",
    "endTime": "18:00"
  },
  "alerts": {
    "entry": true,
    "exit": true,
    "notificationChannels": ["PUSH", "EMAIL", "SMS"]
  }
}

Geofence Creation Response

{
  "vin": "KMHSH81C7LU123456",
  "sessionId": "sess_001",
  "fenceId": "fence-001",
  "name": "Home Area",
  "status": "ACTIVE",
  "createdTime": "2026-03-11T14:40:00Z"
}

Geofence List Response

{
  "vin": "KMHSH81C7LU123456",
  "sessionId": "sess_001",
  "geofences": [
    {
      "fenceId": "fence-001",
      "name": "Home Area",
      "type": "CIRCLE",
      "coordinates": {
        "center": {
          "latitude": 37.5665,
          "longitude": 126.9780
        },
        "radius": 500
      },
      "status": "ACTIVE",
      "createdTime": "2026-03-11T14:40:00Z",
      "lastTriggered": "2026-03-11T15:15:00Z",
      "triggerCount": 3
    }
  ],
  "total": 1
}

Vehicle Location Real-time Update (SSE)

{
  "eventId": "EVT_001",
  "type": "LOCATION_UPDATE",
  "timestamp": "2026-03-11T14:45:00Z",
  "priority": "HIGH",
  "data": {
    "sessionId": "sess_001",
    "vin": "KMHSH81C7LU123456",
    "location": {
      "latitude": 37.5665,
      "longitude": 126.9780,
      "address": "Seoul, Gangnam-gu, Teheran-ro",
      "timestamp": "2026-03-11T14:45:00Z",
      "accuracy": 5.0,
      "speed": 25.5,
      "heading": 180.0
    },
    "vehicleStatus": {
      "batteryLevel": 85,
      "signalStrength": -75,
      "gnssStatus": "NORMAL",
      "networkStatus": "CONNECTED",
      "ignitionStatus": "OFF"
    }
  }
}

Tracking Alert Reception (SSE)

{
  "eventId": "EVT_002",
  "type": "GEOFENCE_TRIGGERED",
  "timestamp": "2026-03-11T15:15:00Z",
  "priority": "MEDIUM",
  "data": {
    "sessionId": "sess_001",
    "vin": "KMHSH81C7LU123456",
    "fenceId": "fence-001",
    "fenceName": "Home Area",
    "alertType": "EXIT",
    "location": {
      "latitude": 37.5665,
      "longitude": 126.9780,
      "address": "Seoul, Gangnam-gu, Teheran-ro",
      "timestamp": "2026-03-11T15:15:00Z"
    }
  }
}

Security and Privacy

Authentication and Authorization

• User authentication token required (JWT/OAuth2)
• Confirm prior consent for theft tracking permissions
• Session-based access control

Data Security

• All API communication encrypted with HTTPS/TLS
• Apply additional encryption for location data transmission
• Store sensitive information only on server, minimize storage on app

Privacy Protection

• Specify purpose of location information collection
• Compliance with data retention period policy
• Guarantee right to data deletion upon user request
• Store tracking logs according to legal requirements

Access Control

• VIN-based vehicle access permission verification
• Grant tracking permissions after theft report verification
• Separate authentication procedures for external agencies (police) access

Exception Handling

Network Related

• Connection Failure: Support offline mode, cache last data
• Slow Response: Loading indicator, timeout handling
• Server Down: Display error message, suggest retry

GPS/Location Related

• Poor GPS Reception: Display last location, notify "low location reliability"
• GNSS Interference: Display location reliability flag, estimate location based on Cell ID
• Indoor Parking: Maintain last outdoor location, display status message

Vehicle Status Related

• Vehicle Offline: Display last location and offline time
• Low Battery: Warning alerts, suggest automatic tracking interval adjustment
• Communication Dead Zone: Continuous status upload, data transmission upon reconnection

App Crash/Error

• App Crash: Data recovery function, automatic session recovery
• Background Processing: Background service for location updates
• Memory Shortage: Data minimization, cache policy

User Error

• Incorrect Case ID: Format validation, request re-entry
• Duplicate Report: Existing report confirmation message
• No Permission: Permission guidance, consent procedure guidance

Test Setup

Base URL: https://api.ecarus.run/api/v1/security
Authentication Token: sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d
Sample VIN: KMHSH81C7LU123456

Use Swagger UI for interactive API testing. Jennifer

Deployment Considerations

App Store Registration

• Clear description of location information collection
• Provide privacy policy
• Request emergency situation alert permissions

Legal Regulation Compliance

• Compliance with location information protection laws by country
• Check data overseas transmission regulations
• Prepare procedures for providing information to law enforcement agencies