운전 습관 분석 API 개발자 가이드

서비스 개요

운전 습관 분석은 차량 주행 데이터를 수집 및 분석하여 운전자의 운전 습관을 평가하고 점수화하는 텔레매틱스 서비스입니다.

서비스 특징

운전 습관 자동 분석 및 점수화
위험 주행 패턴 식별 및 개선 제안
안전 운전 유도를 통한 사고 예방
보험 연계 서비스(UBI) 활용 가능성
개인별 운전 점수 추이 관리

법적 요구사항

개인정보 보호법 준수
주행 데이터 수집 동의 필수
데이터 보유 기간 정책 준수
점수 산정 로직의 투명성 확보

주요 시나리오

시나리오 1: 주행 중 이벤트 감지 및 데이터 수집

엔티티별 API 흐름:

🚗 차량 (TCU):

이벤트 감지: 주행 중 급제동(-0.4g), 급가속(+0.3g) 등 위험 주행 실시간 감지
데이터 버퍼링: 감지된 이벤트를 메모리에 임시 저장
주행 종료 감지: 시동 OFF 시 주행(Trip) 종료 자동 감지
데이터 전송: 주행 요약 데이터를 서버로 전송

🏢 콜센터:

데이터 수신: 차량으로부터 주행 데이터 수신
데이터 유효성 검증: 주행 거리, GPS 노이즈 등 데이터 품질 검증
점수 계산: 100점 만점에서 위험 이벤트별 감점을 통한 최종 점수 산출
등급 부여: 점수에 따른 자동 등급 매핑 (87점 → GRADE_B)
푸시 알림 생성: 운전 점수 리포트 알림 자동 생성

📱 사용자 앱:

푸시 알림 수신: 당일 운전 점수 및 등급 알림 수신
알림 터치: 알림 터치 시 상세 리포트 화면으로 이동

시나리오 2: 운전 점수 상세 조회 및 분석

엔티티별 API 흐름:

📱 사용자 앱:

점수 조회: 최신 운전 점수 상세 조회
기록 조회: 과거 운전 점수 기록 조회
주행 기록 조회: 주행 기록 목록 조회
분석 조회: 운전 습관 상세 분석 조회
통계 조회: 개인 주행 통계 조회
랭킹 조회: 주간 랭킹 조회

🏢 콜센터:

점수 데이터 제공: 실시간 운전 점수 및 등급 정보 제공
기록 데이터 제공: 과거 점수 추이 및 통계 정보 제공
분석 데이터 제공: 운전 패턴 분석 및 개선 제안 제공
랭킹 데이터 제공: 사용자 랭킹 및 비교 데이터 제공

시나리오 3: 위험 주행 패턴 감지 및 비상 대응

엔티티별 API 흐름:

🚗 차량 (TCU):

위험 패턴 감지: 연속된 급제동 등 위험 주행 패턴 실시간 감지
이상 데이터 전송: 위험 주행 데이터 즉시 서버로 전송

🏢 콜센터:

위험 패턴 분석: 반복되는 위험 주행 패턴 자동 식별
위험 수준 평가: 위험 수준 자동 평가 (HIGH/MEDIUM/LOW)
경고 생성: 콜센터에 비상 경고 자동 생성
사용자 컨택: 위험 주행 패턴 관련 전화 컨택 자동 실행

📱 사용자 앱:

비상 컨택 수신: 콜센터로부터 안전 운전 가이드 전화 수신
위험 알림 확인: 현재 위험 주행 패턴 및 개선 제안 확인
점수 영향 확인: 위험 주행이 점수에 미치는 영향 실시간 확인

주요 기능

📱 앱 구현 기능

1. 운전 점수 모니터링

실시간 점수 조회: 현재 운전 점수 및 등급 조회
점수 기록 조회: 과거 점수 기록 및 추이 조회
푸시 알림: 당일 운전 점수 리포트 실시간 수신
대시보드 표시: 점수 원형 차트 및 지도 마커 표시

2. 주행 기록 및 분석

주행 기록 조회: 주행 기록 목록 조회
상세 분석 조회: 운전 습관 상세 분석 조회
개인 통계 조회: 총 주행 거리, 평균 점수 등 통계 조회
행동 패턴 분석: 급제동, 급가속, 과속 등 위험 주행 패턴 식별

3. 경쟁 및 동기부여

주간 랭킹 조회: 주간 랭킹 조회
순위 비교: 타 사용자와의 점수 및 등급 비교
성과 확인: 상위 백분율 및 순위 변동 확인

4. 위험 주행 경고

비상 컨택 수신: 위험 주행 패턴 감지 시 콜센터 전화 수신
위험 알림: 실시간 위험 주행 패턴 및 가이드 수신
개선 제안: 위험 주행 개선을 위한 구체적인 제안 제공

🏢 콜센터 구현 기능

1. 데이터 수집 및 처리

주행 데이터 수신: 차량 주행 데이터 수신
데이터 유효성 검증: 주행 거리, GPS 정확도 등 데이터 품질 검증
이상 데이터 처리: GPS 노이즈 등 이상 데이터 필터링

2. 점수 산정 시스템

실시간 점수 계산: 100점 만점에서 위험 이벤트별 감점을 통한 점수 산출
등급 매핑: 점수 범위에 따른 등급 자동 부여 (S/A/B/C/D)
피드백 생성: 점수에 따른 사용자 피드백 메시지 자동 생성

3. 분석 및 리포팅

행동 패턴 분석: 급제동, 급가속, 과속 빈도 및 추이 분석
위험 수준 평가: 반복되는 위험 주행 패턴의 위험 등급 평가
개선 제안 생성: 운전 습관 개선을 위한 맞춤형 제안 생성

4. 비상 대응 시스템

위험 패턴 감지: 반복되는 위험 주행 패턴 자동 식별
경고 생성: 콜센터 비상 경고 자동 생성
사용자 컨택: 위험 주행 패턴 관련 전화 컨택 자동 실행

5. 데이터 관리

점수 기록 관리: 과거 점수 데이터 저장 및 관리
랭킹 관리: 사용자별 랭킹 데이터 집계 및 관리
통계 관리: 개인별 주행 통계 데이터 관리

시퀀스 다이어그램

운전 습관 분석 시스템 흐름

운전 습관 분석

API 엔드포인트

헤더, 응답 코드 및 에러 형식은 공통 API 사양을 참조하십시오.

운전 점수 조회

bash

curl -X GET "https://api.ecarus.run/api/v1/information/vehicles/KMHSH81C7LU123456/driving-habit/score" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

운전 점수 기록 조회

bash

curl -X GET "https://api.ecarus.run/api/v1/information/vehicles/KMHSH81C7LU123456/driving-habit/score/history?period=30d" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

운전 분석 조회

bash

curl -X GET "https://api.ecarus.run/api/v1/information/vehicles/KMHSH81C7LU123456/driving-habit/analysis?period=30d" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

데이터 모델

운전 점수 정보

json

{
  "scoreId": "score-12345",
  "vin": "KMHSH81C7LU123456",
  "userId": "user123",
  "date": "2026-01-13",
  "totalScore": 82,
  "grade": "GRADE_B",
  "breakdown": {
    "safety": 40,
    "smoothness": 20,
    "compliance": 25,
    "eco": 15
  },
  "tripCount": 5,
  "totalDistance": 45.2,
  "totalDuration": 120,
  "feedback": {
    "code": "FB_WATCH_BRAKING",
    "message": "급감속이 2회 감지되었습니다. 조금 더 부드러운 운전을 시도해 보세요.",
    "priority": "MEDIUM"
  },
  "timestamp": "2026-01-13T23:59:59Z"
}

주행 기록 데이터

json

{
  "tripId": "trip-67890",
  "vin": "KMHSH81C7LU123456",
  "startTime": "2026-01-13T08:30:00Z",
  "endTime": "2026-01-13T09:15:00Z",
  "distance": 15.5,
  "duration": 45,
  "averageSpeed": 20.7,
  "maxSpeed": 65.2,
  "score": 85,
  "grade": "GRADE_B",
  "eventCount": 3,
  "events": [
    {
      "eventType": "HARD_BRAKE",
      "timestamp": "2026-01-13T08:45:12Z",
      "location": { 
        "latitude": 37.123, 
        "longitude": 127.456 
      },
      "severity": "MEDIUM",
      "value": -0.45
    }
  ],
  "route": {
    "startLocation": { "latitude": 37.123, "longitude": 127.456 },
    "endLocation": { "latitude": 37.456, "longitude": 127.789 }
  }
}

운전 점수 기록 응답

json

{
  "period": "30d",
  "scores": [
    {
      "date": "2026-01-13",
      "totalScore": 82,
      "grade": "GRADE_B",
      "breakdown": {
        "safety": 40,
        "smoothness": 20,
        "compliance": 25,
        "eco": 15
      },
      "tripCount": 5,
      "totalDistance": 45.2
    },
    {
      "date": "2026-01-12",
      "totalScore": 78,
      "grade": "GRADE_C",
      "breakdown": {
        "safety": 38,
        "smoothness": 18,
        "compliance": 22,
        "eco": 14
      },
      "tripCount": 3,
      "totalDistance": 28.7
    }
  ],
  "summary": {
    "avgScore": 80.5,
    "maxScore": 85,
    "minScore": 75,
    "grade": "GRADE_B",
    "improvement": "+2.5%",
    "totalTrips": 25,
    "totalDistance": 450.5
  },
  "trend": {
    "direction": "IMPROVING",
    "changeRate": 5.2,
    "consistency": 0.85,
    "weeklyAvg": [78, 82, 85, 80, 83]
  },
  "generatedAt": "2026-01-13T14:30:00Z"
}

운전 분석 응답

json

{
  "period": "30d",
  "analysis": {
    "overallScore": 82,
    "grade": "GRADE_B",
    "behaviorPatterns": {
      "hardAcceleration": {
        "count": 12,
        "frequency": "일일 0.4회",
        "severity": "MEDIUM",
        "trend": "DECREASING",
        "avgAcceleration": 0.35,
        "maxAcceleration": 0.52
      },
      "hardBraking": {
        "count": 8,
        "frequency": "일일 0.27회",
        "severity": "LOW",
        "trend": "STABLE",
        "avgDeceleration": -0.42,
        "maxDeceleration": -0.65
      },
      "sharpCornering": {
        "count": 5,
        "frequency": "일일 0.17회",
        "severity": "LOW",
        "trend": "DECREASING",
        "avgLateralG": 0.35
      },
      "speeding": {
        "count": 3,
        "frequency": "일일 0.1회",
        "severity": "HIGH",
        "trend": "STABLE",
        "avgOverSpeed": 15.2,
        "maxOverSpeed": 28.5
      }
    },
    "improvementAreas": [
      {
        "category": "급가속",
        "frequency": "주당 3회",
        "impact": "MEDIUM",
        "recommendation": "부드러운 가속 습관 개선 필요",
        "potentialScoreGain": 5,
        "priority": 2
      },
      {
        "category": "과속",
        "frequency": "주당 1회",
        "impact": "HIGH",
        "recommendation": "제한 속도 준수 철저",
        "potentialScoreGain": 8,
        "priority": 1
      }
    ],
    "strengths": [
      "제한 속도 준수",
      "안전 거리 유지",
      "부드러운 코너링"
    ],
    "riskFactors": [
      {
        "type": "시간대",
        "description": "퇴근 시간대 위험도 높음",
        "riskLevel": "MEDIUM"
      },
      {
        "type": "도로 유형",
        "description": "고속도로에서 이벤트 빈번",
        "riskLevel": "LOW"
      }
    ]
  },
  "recommendations": [
    "급가속 빈도 줄이기",
    "정속 주행 습관 기르기",
    "충분한 안전 거리 확보"
  ],
  "performanceMetrics": {
    "efficiency": 88.5,
    "safety": 92.0,
    "consistency": 85.2,
    "ecoScore": 82.0
  },
  "generatedAt": "2026-01-13T14:30:00Z"
}

보안 및 프라이버시

인증 및 권한 부여

사용자 인증 토큰 필요 (JWT/OAuth2)
차량 접근 권한 확인
주행 데이터 수집 동의 확인

데이터 보안

모든 API 통신은 HTTPS/TLS 암호화
주행 데이터 전송 시 보안 조치
민감 정보는 서버에만 저장

프라이버시 보호

주행 데이터 수집에 대한 명시적 동의 필수
데이터 수집 목적 명시
데이터 보유 기간 정책 준수
사용자 요청 시 데이터 삭제 권한 보장

접근 제어

VIN 기반 차량 접근 권한 확인
사용자별 주행 데이터 접근 권한 관리
이상 접근 패턴 감지

예외 처리

네트워크 관련

연결 실패: 오프라인 모드 지원, 로컬 데이터 저장
응답 지연: 로딩 인디케이터, 타임아웃 처리
서버 다운: 에러 메시지 표시, 재시도 제안

센서 관련

센서 오류: 센서 오류 알림, 기본값 표시
데이터 부정확: 데이터 신뢰도 낮음 알림
GPS 오류: 위치 정보 오류 처리

데이터 분석 관련

점수 산출 오류: 점수 산출 실패 알림
데이터 부족: 분석 데이터 부족 알림
이상 패턴: 이상 주행 패턴 감지 알림

테스트 설정

Base URL: https://api.ecarus.run/api/v1/information
인증 토큰: sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d
샘플 VIN: KMHSH81C7LU123456

대화형 API 테스트를 위해 Swagger UI를 사용하십시오.

배포 고려사항

앱 스토어 등록

주행 데이터 수집 권한 요청
위치 정보 수집 권한 요청
실시간 데이터 수집에 대한 명확한 설명

법규 준수

개인정보 보호법 준수
주행 데이터 수집 동의 필수
데이터 보유 기간 정책 준수
점수 산정 로직의 투명성 확보

차량 호환성

다양한 차종 지원
센서 유형별 데이터 처리 차이 고려
OEM별 주행 데이터 형식 차이 반영

운전 습관 분석 API 개발자 가이드 ​

서비스 개요 ​

서비스 특징 ​

법적 요구사항 ​

주요 시나리오 ​

시나리오 1: 주행 중 이벤트 감지 및 데이터 수집 ​

시나리오 2: 운전 점수 상세 조회 및 분석 ​

시나리오 3: 위험 주행 패턴 감지 및 비상 대응 ​

주요 기능 ​

📱 앱 구현 기능 ​

1. 운전 점수 모니터링 ​

2. 주행 기록 및 분석 ​

3. 경쟁 및 동기부여 ​

4. 위험 주행 경고 ​

🏢 콜센터 구현 기능 ​

1. 데이터 수집 및 처리 ​

2. 점수 산정 시스템 ​

3. 분석 및 리포팅 ​

4. 비상 대응 시스템 ​

5. 데이터 관리 ​

시퀀스 다이어그램 ​

운전 습관 분석 시스템 흐름 ​

API 엔드포인트 ​

운전 점수 조회 ​

운전 점수 기록 조회 ​

운전 분석 조회 ​

데이터 모델 ​

운전 점수 정보 ​

주행 기록 데이터 ​

운전 점수 기록 응답 ​

운전 분석 응답 ​

보안 및 프라이버시 ​

인증 및 권한 부여 ​

데이터 보안 ​

프라이버시 보호 ​

접근 제어 ​

예외 처리 ​

네트워크 관련 ​

센서 관련 ​

데이터 분석 관련 ​

테스트 설정 ​

배포 고려사항 ​

앱 스토어 등록 ​

법규 준수 ​

차량 호환성 ​

운전 습관 분석 API 개발자 가이드

서비스 개요

서비스 특징

법적 요구사항

주요 시나리오

시나리오 1: 주행 중 이벤트 감지 및 데이터 수집

시나리오 2: 운전 점수 상세 조회 및 분석

시나리오 3: 위험 주행 패턴 감지 및 비상 대응

주요 기능

📱 앱 구현 기능

1. 운전 점수 모니터링

2. 주행 기록 및 분석

3. 경쟁 및 동기부여

4. 위험 주행 경고

🏢 콜센터 구현 기능

1. 데이터 수집 및 처리

2. 점수 산정 시스템

3. 분석 및 리포팅

4. 비상 대응 시스템

5. 데이터 관리

시퀀스 다이어그램

운전 습관 분석 시스템 흐름

API 엔드포인트

운전 점수 조회

운전 점수 기록 조회

운전 분석 조회

데이터 모델

운전 점수 정보

주행 기록 데이터

운전 점수 기록 응답

운전 분석 응답

보안 및 프라이버시

인증 및 권한 부여

데이터 보안

프라이버시 보호

접근 제어

예외 처리

네트워크 관련

센서 관련

데이터 분석 관련

테스트 설정

배포 고려사항

앱 스토어 등록

법규 준수

차량 호환성