Speed Limit API Developer Guide

Service Overview

Speed Limit Service is a safety-focused telematics service that determines speed limit violations based on vehicle location and speed information and provides alerts to guardians or administrators.

Service Features

• Real-time speed detection and speed limit comparison
• Regional speed limit policy application
• Child protection zone specialized safety functions
• Immediate guardian alert provision
• Driving habit improvement support

Legal Requirements

• Compliance with speed limit regulations around schools and parks
• Mandatory location information collection consent
• Compliance with personal information protection laws
• Driver prior consent required

Key Scenarios

Scenario 1: Speed Limit Policy Setting

API Flow by Entity:

📱 App (User):

1. Set Policy: Set maximum speed and time periods
2. Query Policy: Verify currently configured speed limit policies

🚗 Vehicle (TCU):

1. Speed Transmission: Periodically transmit real-time speed and location information
2. Status Report: Report current speed status to ECARUS server

🏢 Call Center:

1. Event Monitoring: Monitor real-time speed violation events
2. History Check: Check past speed violation records

Key Features

App Features

• Policy Setting: Set maximum speed, time periods, regional zones
• Policy Query: Check currently configured speed limit policies
• Real-time Monitoring: Receive real-time alerts via SSE stream
• Violation History: Check past speed violation records
• Emergency Support: Temporary monitoring enhancement

Call Center Features

• Policy Management: Manage overall speed limit policies and Manage overall speed limit policies
• Alert Monitoring: Real-time violation situation monitoring
• History Management: Manage speed violation history
• Warning System: Transmit warning sound to vehicle for speed violations

Sequence Diagram

Speed Limit System Flow

API Endpoints

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

(1) Speed Limit Management

Speed Limit Policy Query

curl -X GET "https://api.ecarus.run/api/v1/childcare/vehicles/KMHSH81C7LU123456/speed-limit/policy" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

Speed Limit Policy Update

curl -X POST "https://api.ecarus.run/api/v1/childcare/vehicles/KMHSH81C7LU123456/speed-limit/config" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{
           "speedLimit": 30,
           "timeWindow": {"start": "08:00", "end": "20:00"},
           "geoZones": ["school"],
           "graceSeconds": 3
         }'

(2) Speed Limit Violation Detection (SSE)

Note: Recommend accessing via browser or using dedicated SSE client

curl -N -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     "https://api.ecarus.run/api/v1/childcare/vehicles/KMHSH81C7LU123456/speed-limit/events"

Data Models

Speed Limit Policy Structure

{
  "policyId": "speed-policy-12345",
  "vin": "KMHSH81C7LU123456",
  "name": "School Zone Speed Limit",
  "speedLimit": 30,
  "timeWindow": {
    "start": "08:00",
    "end": "20:00"
  },
  "geoZones": [
    {
      "type": "school",
      "radius": 300,
      "center": {"latitude": 37.5665, "longitude": 126.9780}
    }
  ],
  "active": true
}

Real-time Event Format

{
  "eventId": "speed-violation-67890",
  "vin": "KMHSH81C7LU123456",
  "timestamp": "2026-01-13T08:30:00Z",
  "severity": "WARNING",
  "location": {
    "latitude": 37.5665,
    "longitude": 126.9780,
    "address": "2 Taepyeong-ro, Jung-gu, Seoul"
  },
  "vehicleSpeed": 45.5,
  "speedLimit": 30,
  "message": "Currently driving at 45km/h, exceeding speed limit of 30km/h."
}

Speed Violation Record

{
  "violationId": "vio-001",
  "vin": "KMHSH81C7LU123456",
  "policyId": "speed-policy-12345",
  "timestamp": "2026-01-13T08:30:00Z",
  "severity": "WARNING",
  "location": {
    "latitude": 37.5665,
    "longitude": 126.9780,
    "address": "2 Taepyeong-ro, Jung-gu, Seoul"
  },
  "vehicleSpeed": 45.5,
  "speedLimit": 30,
  "duration": 8
}

Security and Privacy

Authentication and Authorization

• User authentication token required (JWT/OAuth2)
• Vehicle access permission verification
• Speed limit policy setting permission
• Location information collection consent

Data Security

• All API communication encrypted with HTTPS/TLS
• Security measures when transmitting speed information
• Sensitive location information stored only on server

Privacy Protection

• Mandatory location information collection consent
• Driver prior consent required
• Compliance with data retention period policies
• Guarantee right to data deletion upon user request

Access Control

• VIN-based vehicle access permission verification
• User-specific speed limit policy access management
• Speed violation history access control
• Abnormal access pattern detection

Exception Handling

Network Related

• Connection Failure: Offline mode support, store data and retransmit
• Slow Response: Loading indicator, timeout handling
• Server Down: Display error message, suggest retry

GPS Related

• GPS Reception Unavailable: Use last known location information
• Location Error: Apply GPS error correction algorithm
• Indoor Parking: Guide indoor location inaccuracy

Speed Detection Related

• Speed Sensor Error: Multi-sensor cross-verification
• Temporary Speed Data Loss: Use estimated speed data
• Speed Accuracy Issues: Speed data calibration

Policy Related

• Policy Setting Error: Policy configuration validation
• Policy Conflict: Multi-policy conflict resolution
• Policy Application Failure: Policy retry mechanism

Test Setup

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

Use Swagger UI for interactive API testing.

Deployment Considerations

App Store Registration

• Request location information collection permissions
• Request speed monitoring permissions
• Clear explanation of speed limit functionality

Legal Regulation Compliance

• Compliance with speed limit regulations around schools and parks
• Mandatory location information collection consent
• Compliance with personal information protection laws
• Driver prior consent requirement

Speed Detection Accuracy

• GPS-based speed detection optimization
• Speed sensor data calibration
• Real-time speed processing optimization
• Speed data quality management

Performance Optimization

• Real-time speed violation detection optimization
• Large-scale speed monitoring support
• Speed limit policy application efficiency
• Alert transmission speed improvement