주행 정보 API 개발자 가이드 (Driving Information API Developer Guide)

서비스 개요

주행 정보 서비스는 차량 주행 중에 발생하는 다양한 데이터를 수집 및 저장하여 차량의 주행 패턴 및 차량 상태 분석이 가능하도록 지원하는 텔레매틱스 기반 데이터 서비스입니다.

서비스 특징

실시간 주행 데이터 수집 및 저장
주행(Trip) 기반의 주행 요약 정보 제공
차량 상태 및 성능 분석 기반 데이터 제공
다양한 분석 서비스의 기초 데이터 제공
스트림 기반 실시간 데이터 처리

법적 요구사항

개인정보 보호법 준수
주행 데이터 수집 동의 필수
데이터 보유 기간 정책 준수
위치 정보 수집 목적의 명시

주요 시나리오

시나리오 1: 주행 종료 및 데이터 전송

엔티티별 API 흐름:

🚗 차량 (TCU):

주행 종료 감지: 시동 OFF 시 주행(Trip) 종료 자동 감지
주행 데이터 생성: 주행 요약 데이터의 자동 생성
데이터 전송: 주행 요약 데이터를 서버로 전송

🏢 콜센터:

주행 데이터 수신: 차량으로부터 주행 요약 데이터 수신
데이터 처리: 수신된 데이터의 저장 및 가공
요약 정보 생성: 주행별 상세 요약 정보 생성

시나리오 2: 주행 목록 조회 및 상세 정보 확인

엔티티별 API 흐름:

📱 사용자 앱:

주행 목록 조회: 최근 주행 목록 조회
주행 목록 표시: 화면에 주행 목록 표시
주행 상세 조회: 선택된 주행 상세 정보 조회
지도 표시: 주행 상세 경로 지도 표시

🏢 콜센터:

주행 목록 제공: 주행 목록 데이터 제공
주행 상세 제공: 주행 상세 정보 및 경로 데이터 제공
데이터 검색: 조건에 맞는 주행 데이터 검색

시나리오 3: 주행 통계 조회 및 분석

엔티티별 API 흐름:

📱 사용자 앱:

통계 조회: 주행 통계 조회
통계 확인: 총 주행 거리, 평균 연비, 주행 횟수 등 통계 확인
패턴 분석: 주행 패턴 및 성능 분석 결과 확인

🏢 콜센터:

통계 생성: 주행 데이터를 기반으로 통계 정보 자동 생성
분석 처리: 연비, 주행 패턴 등 분석 처리
인사이트 도출: 운전 습관 관련 인사이트 제공

시나리오 4: 주행 기록 검색 및 데이터 추출

엔티티별 API 흐름:

📱 사용자 앱:

기록 검색: 기간별 주행 기록 검색
데이터 추출: 리포트 추출 기능 실행
결과 확인: 검색 결과 및 추출된 파일 확인

🏢 콜센터:

검색 처리: 조건에 따른 주행 기록 검색 처리
추출 생성: PDF/CSV 형식의 리포트 생성
파일 제공: 생성된 리포트 파일 다운로드 제공

주요 기능

📱 앱 구현 기능

1. 주행 관리

주행 목록 조회: 최근 주행 목록 조회
주행 상세 조회: 주행 상세 정보 및 경로 조회
주행 이력 관리: 월별 주행 이력 관리
지도 시각화: 주행 경로의 지도 시각화

2. 주행 통계 및 분석

통계 조회: 주행 통계 조회
연비 분석: 평균 연비 및 연비 성능 분석
주행 패턴 분석: 운전 습관 및 패턴 분석
성능 확인: 주행 성능 및 변화 추이 확인

3. 데이터 검색 및 필터링

기간 검색: 기간별 주행 기록 검색
위치 기반 검색: 특정 지역의 주행 기록 검색
조건 필터링: 거리, 시간, 연비 등 조건별 필터링

4. 데이터 추출 및 공유

리포트 생성: 주행 데이터 PDF/CSV 리포트 생성
데이터 공유: 주행 정보 및 통계 데이터 공유
백업 관리: 개인 주행 데이터의 백업

5. 실시간 알림

주행 시작/종료 알림: 주행의 시작과 종료 실시간 알림
이상 패턴 알림: 이상 주행 패턴 감지 시 알림
안전 점검 알림: 이상 상태 시 안전 점검 요청 알림

🏢 콜센터 구현 기능

1. 주행 데이터 관리

주행 데이터 수신: 주행 요약 데이터 수신
주행 목록 관리: 주행 목록 데이터 관리
주행 상세 관리: 주행 상세 정보 관리
주행 이력 관리: 주행 이력 데이터 관리

2. 주행 데이터 처리

실시간 데이터 처리: 주행 데이터의 실시간 수집 및 처리
데이터 검증: 수신된 데이터의 유효성 검증
요약 정보 생성: 주행별 요약 정보의 자동 생성
데이터 저장: 처리된 데이터의 안전한 저장

3. 통계 및 분석

통계 생성: 주행 통계 정보의 자동 생성
연비 분석: 연비 성능 및 추이 분석
주행 패턴 분석: 운전 습관 패턴 자동 분석
인사이트 도출: 주행 데이터 기반 인사이트 도출

4. 검색 및 추출

검색 처리: 조건에 따른 주행 기록 검색 처리
필터링 처리: 다양한 조건에 따른 데이터 필터링
리포트 생성: PDF/CSV 형식의 리포트 자동 생성
파일 관리: 생성된 리포트 파일 관리

5. 이상 감지 및 알림

이상 패턴 감지: 이상 주행 패턴의 자동 감지
위험 수준 평가: 이상 패턴의 위험 수준 자동 평가
경고 생성: 콜센터 비상 경고 자동 생성
사용자 통보: 사용자에게 안전 점검 알림 전송

6. API 서비스 관리

API 응답 처리: 주행 관련 API 요청 처리
데이터 제공: 클라이언트에게 주행 데이터 제공
성능 모니터링: API 응답 시간 및 가용성 모니터링
에러 핸들링: 데이터 조회 및 처리 에러 대응

시퀀스 다이어그램

주행 정보 시스템 흐름

주행 정보

API 엔드포인트

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

주행 최근 조회

bash

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

주행 이력 목록 조회

bash

curl -X GET "https://api.ecarus.run/api/v1/information/vehicles/KMHSH81C7LU123456/driving-history/list?month=2024-03" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

주행 상세 정보 및 경로 조회

bash

curl -X GET "https://api.ecarus.run/api/v1/information/vehicles/KMHSH81C7LU123456/driving-history/detail-path?tripId=trip_001" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

주행 통계 조회

bash

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

주행 검색

bash

curl -X GET "https://api.ecarus.run/api/v1/information/vehicles/KMHSH81C7LU123456/driving-history/search?from=2024-03-01&to=2024-03-31" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

데이터 모델

주행 목록 응답 (Trip List Response)

json

{
  "vin": "KMHSH81C7LU123456",
  "trips": [
    {
      "tripId": "trip-12345",
      "startTime": "2026-01-13T08:30:00Z",
      "endTime": "2026-01-13T09:15:00Z",
      "date": "2026-01-13",
      "distance": 15.5,
      "duration": 45,
      "averageSpeed": 20.7,
      "maxSpeed": 65.2,
      "fuelConsumption": 1.2,
      "status": "COMPLETED",
      "eventCount": 2,
      "route": {
        "startLocation": { "latitude": 37.123, "longitude": 127.456 },
        "endLocation": { "latitude": 37.456, "longitude": 127.789 }
      }
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "pageSize": 10,
    "hasNext": false,
    "hasPrev": false
  },
  "summary": {
    "totalDistance": 15.5,
    "totalDuration": 45,
    "averageSpeed": 20.7
  }
}

주행 이력 목록 응답 (Trip History List Response)

json

{
  "month": "2024-03",
  "vin": "KMHSH81C7LU123456",
  "trips": [
    {
      "tripId": "trip-12345",
      "startTime": "2026-01-13T08:30:00Z",
      "endTime": "2026-01-13T09:15:00Z",
      "date": "2026-01-13",
      "distance": 15.5,
      "duration": 45,
      "averageSpeed": 20.7,
      "maxSpeed": 65.2,
      "fuelConsumption": 1.2,
      "eventCount": 2,
      "status": "COMPLETED"
    }
  ],
  "summary": {
    "totalTrips": 25,
    "totalDistance": 450.5,
    "totalDuration": 1200,
    "averageSpeed": 22.5,
    "averageFuelConsumption": 12.9,
    "fuelEfficiency": {
      "average": 12.9,
      "best": 15.2,
      "worst": 10.1,
      "trend": "IMPROVING"
    },
    "drivingPatterns": {
      "averageDailyDistance": 15.0,
      "averageTripDuration": 48.0,
      "peakHours": ["08:00-09:00", "18:00-19:00"]
    }
  },
  "generatedAt": "2026-01-13T14:30:00Z"
}

주행 상세 정보 및 경로 응답 (Trip Detailed Information and Route Response)

json

{
  "tripId": "trip-12345",
  "vin": "KMHSH81C7LU123456",
  "startTime": "2026-01-13T08:30:00Z",
  "endTime": "2026-01-13T09:15:00Z",
  "date": "2026-01-13",
  "distance": 15.5,
  "duration": 45,
  "averageSpeed": 20.7,
  "maxSpeed": 65.2,
  "fuelConsumption": 1.2,
  "status": "COMPLETED",
  "eventCount": 2,
  "route": {
    "startLocation": {
      "latitude": 37.123,
      "longitude": 127.456,
      "address": "서울시 강남구 테헤란로 123",
      "timestamp": "2026-01-13T08:30:00Z"
    },
    "endLocation": {
      "latitude": 37.456,
      "longitude": 127.789,
      "address": "서울시 서초구 서초대로 456",
      "timestamp": "2026-01-13T09:15:00Z"
    },
    "path": [
      {
        "latitude": 37.123,
        "longitude": 127.456,
        "timestamp": "2026-01-13T08:30:00Z",
        "speed": 0.0
      },
      {
        "latitude": 37.234,
        "longitude": 127.567,
        "timestamp": "2026-01-13T08:45:00Z",
        "speed": 45.5
      }
    ],
    "totalWaypoints": 120,
    "pathAccuracy": "HIGH"
  },
  "events": [
    {
      "eventId": "evt-001",
      "eventType": "HARD_BRAKE",
      "timestamp": "2026-01-13T08:45:12Z",
      "location": {
        "latitude": 37.234,
        "longitude": 127.567
      },
      "severity": "MEDIUM",
      "value": -0.45,
      "threshold": -0.4,
      "speed": 45.5,
      "roadType": "CITY"
    }
  ],
  "drivingAnalysis": {
    "highwayRatio": 0.3,
    "cityRatio": 0.7,
    "nightDrivingRatio": 0.1,
    "idleTime": 180,
    "ecoDrivingScore": 85
  },
  "generatedAt": "2026-01-13T14:30:00Z"
}

주행 통계 응답 (Trip Statistics Response)

json

{
  "period": "30d",
  "vin": "KMHSH81C7LU123456",
  "statistics": {
    "totalTrips": 25,
    "totalDistance": 450.5,
    "totalDuration": 1200,
    "averageSpeed": 22.5,
    "averageFuelConsumption": 12.9,
    "fuelEfficiency": {
      "average": 12.9,
      "best": 15.2,
      "worst": 10.1,
      "trend": "IMPROVING",
      "totalFuelUsed": 34.9
    },
    "drivingPatterns": {
      "averageDailyDistance": 15.0,
      "averageTripDuration": 48.0,
      "peakHours": ["08:00-09:00", "18:00-19:00"],
      "mostActiveDay": "금요일",
      "leastActiveDay": "일요일"
    },
    "roadTypes": {
      "highway": {
        "distance": 135.2,
        "ratio": 0.3,
        "averageSpeed": 65.5
      },
      "city": {
        "distance": 315.3,
        "ratio": 0.7,
        "averageSpeed": 18.2
      }
    },
    "eventSummary": {
      "hardAcceleration": {
        "count": 12,
        "frequency": "주행당 0.4회",
        "trend": "DECREASING"
      },
      "hardBrake": {
        "count": 8,
        "frequency": "주행당 0.27회",
        "trend": "STABLE"
      },
      "sharpCornering": {
        "count": 5,
        "frequency": "주행당 0.17회",
        "trend": "DECREASING"
      },
      "speeding": {
        "count": 3,
        "frequency": "주행당 0.1회",
        "trend": "STABLE"
      }
    },
    "timeAnalysis": {
      "daytimeTrips": 20,
      "nightTrips": 5,
      "weekendTrips": 8,
      "weekdayTrips": 17,
      "averageTripStartTime": "09:30"
    }
  },
  "comparisons": {
    "previousPeriod": {
      "distanceChange": "+5.2%",
      "fuelEfficiencyChange": "+2.1%",
      "eventCountChange": "-12.5%"
    }
  },
  "generatedAt": "2026-01-13T14:30:00Z"
}

주행 검색 응답 (Trip Search Response)

json

{
  "from": "2024-03-01",
  "to": "2024-03-31",
  "vin": "KMHSH81C7LU123456",
  "trips": [
    {
      "tripId": "trip-12345",
      "startTime": "2026-01-13T08:30:00Z",
      "endTime": "2026-01-13T09:15:00Z",
      "date": "2026-01-13",
      "distance": 15.5,
      "duration": 45,
      "averageSpeed": 20.7,
      "maxSpeed": 65.2,
      "fuelConsumption": 1.2,
      "eventCount": 2,
      "status": "COMPLETED"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "pageSize": 20,
    "hasNext": false,
    "hasPrev": false
  },
  "filters": {
    "dateRange": {
      "from": "2024-03-01",
      "to": "2024-03-31"
    },
    "minDistance": null,
    "maxDistance": null,
    "eventTypes": [],
    "roadTypes": null,
    "timeRange": null
  },
  "summary": {
    "totalDistance": 15.5,
    "totalDuration": 45,
    "averageSpeed": 20.7,
    "totalFuelConsumption": 1.2,
    "totalEvents": 2
  },
  "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 개발자 가이드 (Driving Information API Developer Guide) ​

서비스 개요 ​

서비스 특징 ​

법적 요구사항 ​

주요 시나리오 ​

시나리오 1: 주행 종료 및 데이터 전송 ​

시나리오 2: 주행 목록 조회 및 상세 정보 확인 ​

시나리오 3: 주행 통계 조회 및 분석 ​

시나리오 4: 주행 기록 검색 및 데이터 추출 ​

주요 기능 ​

📱 앱 구현 기능 ​

1. 주행 관리 ​

2. 주행 통계 및 분석 ​

3. 데이터 검색 및 필터링 ​

4. 데이터 추출 및 공유 ​

5. 실시간 알림 ​

🏢 콜센터 구현 기능 ​

1. 주행 데이터 관리 ​

2. 주행 데이터 처리 ​

3. 통계 및 분석 ​

4. 검색 및 추출 ​

5. 이상 감지 및 알림 ​

6. API 서비스 관리 ​

시퀀스 다이어그램 ​

주행 정보 시스템 흐름 ​

API 엔드포인트 ​

주행 최근 조회 ​

주행 이력 목록 조회 ​

주행 상세 정보 및 경로 조회 ​

주행 통계 조회 ​

주행 검색 ​

데이터 모델 ​

주행 목록 응답 (Trip List Response) ​

주행 이력 목록 응답 (Trip History List Response) ​

주행 상세 정보 및 경로 응답 (Trip Detailed Information and Route Response) ​

주행 통계 응답 (Trip Statistics Response) ​

주행 검색 응답 (Trip Search Response) ​

보안 및 프라이버시 ​

인증 및 권한 부여 ​

데이터 보안 ​

프라이버시 보호 ​

접근 제어 ​

예외 처리 ​

네트워크 관련 ​

센서 관련 ​

데이터 처리 관련 ​

테스트 설정 ​

배포 고려사항 ​

앱 스토어 등록 ​

법규 준수 ​

차량 호환성 ​

주행 정보 API 개발자 가이드 (Driving Information API Developer Guide)

서비스 개요

서비스 특징

법적 요구사항

주요 시나리오

시나리오 1: 주행 종료 및 데이터 전송

시나리오 2: 주행 목록 조회 및 상세 정보 확인

시나리오 3: 주행 통계 조회 및 분석

시나리오 4: 주행 기록 검색 및 데이터 추출

주요 기능

📱 앱 구현 기능

1. 주행 관리

2. 주행 통계 및 분석

3. 데이터 검색 및 필터링

4. 데이터 추출 및 공유

5. 실시간 알림

🏢 콜센터 구현 기능

1. 주행 데이터 관리

2. 주행 데이터 처리

3. 통계 및 분석

4. 검색 및 추출

5. 이상 감지 및 알림

6. API 서비스 관리

시퀀스 다이어그램

주행 정보 시스템 흐름

API 엔드포인트

주행 최근 조회

주행 이력 목록 조회

주행 상세 정보 및 경로 조회

주행 통계 조회

주행 검색

데이터 모델

주행 목록 응답 (Trip List Response)

주행 이력 목록 응답 (Trip History List Response)

주행 상세 정보 및 경로 응답 (Trip Detailed Information and Route Response)

주행 통계 응답 (Trip Statistics Response)

주행 검색 응답 (Trip Search Response)

보안 및 프라이버시

인증 및 권한 부여

데이터 보안

프라이버시 보호

접근 제어

예외 처리

네트워크 관련

센서 관련

데이터 처리 관련

테스트 설정

배포 고려사항

앱 스토어 등록

법규 준수

차량 호환성