속도 제한(Speed Limit) API 개발자 가이드
서비스 개요
속도 제한(Speed Limit) 서비스는 차량의 위치와 속도 정보를 기반으로 속도 위반 여부를 판별하여 보호자나 관리자에게 알림을 제공하는 안전 중심의 텔레매틱스 서비스입니다.
서비스 특징
- 실시간 속도 감지 및 제한 속도 비교
- 지역별 속도 제한 정책 적용
- 어린이 보호 구역 특화 안전 기능
- 보호자 즉시 알림 제공
- 운전 습관 개선 지원
법적 요구사항
- 학교 및 공원 주변 속도 제한 규정 준수
- 위치정보 수집 동의 필수
- 개인정보 보호법 준수
- 운전자 사전 동의 필수
주요 시나리오
시나리오 1: 속도 제한 정책 설정
엔티티별 API 흐름:
📱 앱 (사용자):
- 정책 설정: 최고 속도 및 시간대 설정
- 정책 조회: 현재 설정된 속도 제한 정책 확인
🚗 차량 (TCU):
- 속도 전송: 주기적으로 실시간 속도 및 위치 정보 전송
- 상태 보고: 현재 속도 상태를 ECARUS 서버에 보고
🏢 콜센터:
- 이벤트 모니터링: 실시간 속도 위반 이벤트 모니터링
- 이력 확인: 과거 속도 위반 기록 확인
주요 기능
앱 기능
- 정책 설정: 최고 속도, 시간대, 지역 존 설정
- 정책 조회: 현재 설정된 속도 제한 정책 확인
- 실시간 모니터링: SSE 스트림을 통한 실시간 알림 수신
- 위반 이력: 과거 속도 위반 기록 확인
- 비상 지원: 일시적 모니터링 강화
콜센터 기능
- 정책 관리: 전체 속도 제한 정책 관리 및 전체 속도 제한 정책 업데이트
- 알림 모니터링: 실시간 위반 상황 모니터링
- 이력 관리: 속도 위반 이력 관리
- 경고 시스템: 속도 위반 시 차량으로 경고음 송출
시퀀스 다이어그램
속도 제한 시스템 흐름
API 엔드포인트
헤더, 응답 코드 및 에러 형식은 공통 API 사양을 참조하십시오.
(1) 속도 제한 관리
속도 제한 정책 조회
bash
curl -X GET "https://api.ecarus.run/api/v1/childcare/vehicles/KMHSH81C7LU123456/speed-limit/policy" \
-H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"속도 제한 정책 업데이트
bash
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) 속도 제한 위반 감지 (SSE)
참고: 브라우저를 통해 접속하거나 전용 SSE 클라이언트 사용 권장
bash
curl -N -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
"https://api.ecarus.run/api/v1/childcare/vehicles/KMHSH81C7LU123456/speed-limit/events"데이터 모델
속도 제한 정책 구조
json
{
"policyId": "speed-policy-12345",
"vin": "KMHSH81C7LU123456",
"name": "어린이 보호 구역 속도 제한",
"speedLimit": 30,
"timeWindow": {
"start": "08:00",
"end": "20:00"
},
"geoZones": [
{
"type": "school",
"radius": 300,
"center": {"latitude": 37.5665, "longitude": 126.9780}
}
],
"active": true
}실시간 이벤트 형식
json
{
"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": "현재 45km/h로 주행 중이며, 제한 속도 30km/h를 초과했습니다."
}속도 위반 기록
json
{
"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
}보안 및 프라이버시
인증 및 권한 부여
- 사용자 인증 토큰 필요 (JWT/OAuth2)
- 차량 접근 권한 확인
- 속도 제한 정책 설정 권한
- 위치정보 수집 동의
데이터 보안
- 모든 API 통신은 HTTPS/TLS 암호화
- 속도 데이터 전송 시 보안 조치
- 민감 위치 정보는 서버에만 저장
프라이버시 보호
- 위치정보 수집 동의 필수
- 운전자 사전 동의 필수
- 데이터 보유 기간 정책 준수
- 사용자 요청 시 데이터 삭제 권한 보장
접근 제어
- VIN 기반 차량 접근 권한 확인
- 사용자별 속도 제한 정책 접근 관리
- 속도 위반 이력 접근 제어
- 이상 접근 패턴 감지
예외 처리
네트워크 관련
- 연결 실패: 오프라인 모드 지원, 데이터 저장 후 재전송
- 응답 지연: 로딩 인디케이터, 타임아웃 처리
- 서버 다운: 에러 메시지 표시, 재시도 제안
GPS 관련
- GPS 수신 불가: 마지막 확인 위치 정보 사용
- 위치 오류: GPS 오차 보정 알고리즘 적용
- 실내 주차: 실내 위치 부정확 안내
속도 감지 관련
- 속도 센서 오류: 멀티 센서 교차 검증
- 일시적 속도 데이터 손실: 추정 속도 데이터 사용
- 속도 정확도 이슈: 속도 데이터 캘리브레이션
정책 관련
- 정책 설정 오류: 정책 설정 유효성 검사
- 정책 충돌: 다중 정책 충돌 해결
- 정책 적용 실패: 정책 재시도 메커니즘
테스트 설정
Base URL: https://api.ecarus.run/api/v1/childcare
인증 토큰: sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d
샘플 VIN: KMHSH81C7LU123456
대화형 API 테스트를 위해 Swagger UI를 사용하십시오.
배포 고려사항
앱 스토어 등록
- 위치정보 수집 권한 요청
- 속도 모니터링 권한 요청
- 속도 제한 기능에 대한 명확한 설명
법규 준수
- 학교 및 공원 주변 속도 제한 규정 준수
- 위치정보 수집 동의 필수
- 개인정보 보호법 준수
- 운전자 사전 동의 필수
속도 감지 정확성
- GPS 기반 속도 감지 최적화
- 속도 센서 데이터 캘리브레이션
- 실시간 속도 처리 최적화
- 속도 데이터 품질 관리
성능 최적화
- 실시간 속도 위반 감지 최적화
- 대규모 속도 모니터링 지원
- 속도 제한 정책 적용 효율성
- 알림 전송 속도 개선