Driving Habit Analysis API Developer Guide

Service Overview

Driving Habit Analysis is a telematics service that collects and analyzes vehicle driving data to evaluate and score driver driving habits.

Service Features

Automatic driving habit analysis and scoring
Identification and improvement suggestions for risky driving patterns
Accident prevention through safe driving guidance
Possible linkage with insurance-based services (UBI)
Individual driving score trend management

Legal Requirements

Compliance with personal information protection laws
Mandatory driving data collection consent
Compliance with data retention period policies
Ensure transparency of scoring logic

Key Scenarios

Scenario 1: Event Detection During Driving and Data Collection

API Flow by Entity:

🚗 Vehicle (TCU):

Event Detection: Real-time detection of risky driving during driving such as hard braking (-0.4g), hard acceleration (+0.3g)
Data Buffering: Temporarily store detected events in memory
Driving End Detection: Automatic detection of Trip end when engine is OFF
Data Transmission: Transmit Trip summary data to server

🏢 Call Center:

Data Reception: Receive Trip data from vehicle
Data Validity Verification: Verify data quality such as driving distance, GPS noise
Score Calculation: Calculate final score by deducting points from base score of 100 for risky events
Grade Assignment: Automatic grade mapping based on score (87 points → GRADE_B)
Push Notification Generation: Automatic generation of driving score report notifications

📱 User App:

Push Notification Reception: Receive daily driving score and grade notifications
Notification Touch: Touch notification to move to detailed report screen

Scenario 2: Driving Score Detailed Query and Analysis

API Flow by Entity:

📱 User App:

Score Query: Query latest driving score details
Record Query: Query past driving score records
Trip Record Query: Query driving record list
Analysis Query: Query driving habit detailed analysis
Statistics Query: Query personal driving statistics
Ranking Query: Query weekly ranking

🏢 Call Center:

Score Data Provision: Provide real-time driving score and grade information
Record Data Provision: Provide past score trends and statistical information
Analysis Data Provision: Provide driving pattern analysis and improvement suggestions
Ranking Data Provision: Provide user ranking and comparison data

Scenario 3: Risky Driving Pattern Detection and Emergency Response

API Flow by Entity:

🚗 Vehicle (TCU):

Risk Pattern Detection: Real-time detection of risky driving patterns such as repeated hard braking
Abnormal Data Transmission: Immediate transmission of abnormal driving data to server

🏢 Call Center:

Risk Pattern Analysis: Automatic identification of repeated risky driving patterns
Risk Assessment: Automatic assessment of risk level (HIGH/MEDIUM/LOW)
Warning Generation: Automatic generation of emergency warnings to call center
User Contact: Automatic execution of phone contact regarding risky driving patterns

📱 User App:

Emergency Contact Reception: Receive safe driving guidance phone call from call center
Risk Notification Check: Check current risky driving patterns and improvement suggestions
Score Impact Check: Real-time check of impact of risky driving on score

Key Features

📱 Features to Implement in App

1. Driving Score Monitoring

Real-time Score Query: Query current driving score and grade
Score Record Query: Query past score records and trends
Push Notifications: Real-time reception of daily driving score reports
Dashboard Display: Display score circular chart and map markers

2. Driving Records and Analysis

Trip Record Query: Query driving record list
Detailed Analysis Query: Query driving habit detailed analysis
Personal Statistics Query: Statistics such as total driving distance, average score
Behavior Pattern Analysis: Identify risky driving patterns such as hard braking, hard acceleration, speeding

3. Competition and Motivation

Weekly Ranking Query: Query weekly ranking
Rank Comparison: Compare scores and grades with other users
Performance Check: Check top percentile and ranking changes

4. Risky Driving Alerts

Emergency Contact Reception: Receive call center phone call when risky driving patterns detected
Risk Notifications: Receive real-time risky driving patterns and guidance
Improvement Suggestions: Provide specific suggestions for risky driving improvement

🏢 Features to Implement in Call Center

1. Data Collection and Processing

Trip Data Reception: Receive vehicle driving data
Data Validity Verification: Verify data quality such as driving distance, GPS accuracy
Abnormal Data Processing: Filter abnormal data such as GPS noise

2. Scoring System

Real-time Score Calculation: Calculate score by deducting points from base score of 100 for risky events
Grade Mapping: Automatic assignment of grades (S/A/B/C/D) based on score range
Feedback Generation: Automatic generation of user feedback messages based on score

3. Analysis and Reporting

Behavior Pattern Analysis: Analyze frequency and trends of hard braking, hard acceleration, speeding
Risk Assessment: Assess risk level of repeated risky driving patterns
Improvement Suggestions: Provide personalized suggestions for driving habit improvement

4. Emergency Response System

Risk Pattern Detection: Automatic detection of repeated risky driving patterns
Warning Generation: Automatic generation of emergency warnings to call center
User Contact: Automatic execution of phone contact regarding risky driving patterns

5. Data Management

Score Record Management: Store and manage past score data
Ranking Management: Aggregate and manage user ranking data
Statistics Management: Manage personal driving statistics data

Sequence Diagram

Driving Habit Analysis System Flow

Driving Habit Analysis

API Endpoints

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

Driving Score Query

bash

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

Driving Score Record Query

bash

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

Driving Analysis Query

bash

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

Data Models

Driving Score Information

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 hard decelerations detected. Please try to be more gentle.",
    "priority": "MEDIUM"
  },
  "timestamp": "2026-01-13T23:59:59Z"
}

Driving Record Data

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 }
  }
}

Driving Score Record Response

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"
}

Driving Analysis Response

json

{
  "period": "30d",
  "analysis": {
    "overallScore": 82,
    "grade": "GRADE_B",
    "behaviorPatterns": {
      "hardAcceleration": {
        "count": 12,
        "frequency": "0.4 per day",
        "severity": "MEDIUM",
        "trend": "DECREASING",
        "avgAcceleration": 0.35,
        "maxAcceleration": 0.52
      },
      "hardBraking": {
        "count": 8,
        "frequency": "0.27 per day",
        "severity": "LOW",
        "trend": "STABLE",
        "avgDeceleration": -0.42,
        "maxDeceleration": -0.65
      },
      "sharpCornering": {
        "count": 5,
        "frequency": "0.17 per day",
        "severity": "LOW",
        "trend": "DECREASING",
        "avgLateralG": 0.35
      },
      "speeding": {
        "count": 3,
        "frequency": "0.1 per day",
        "severity": "HIGH",
        "trend": "STABLE",
        "avgOverSpeed": 15.2,
        "maxOverSpeed": 28.5
      }
    },
    "improvementAreas": [
      {
        "category": "Hard Acceleration",
        "frequency": "3 times per week",
        "impact": "MEDIUM",
        "recommendation": "Smooth acceleration habit improvement needed",
        "potentialScoreGain": 5,
        "priority": 2
      },
      {
        "category": "Speeding",
        "frequency": "1 time per week",
        "impact": "HIGH",
        "recommendation": "Strict speed limit compliance",
        "potentialScoreGain": 8,
        "priority": 1
      }
    ],
    "strengths": [
      "Speed limit compliance",
      "Safe following distance maintenance",
      "Smooth cornering"
    ],
    "riskFactors": [
      {
        "type": "TIME_OF_DAY",
        "description": "Higher risk during evening rush hours",
        "riskLevel": "MEDIUM"
      },
      {
        "type": "ROAD_TYPE",
        "description": "More events on highways",
        "riskLevel": "LOW"
      }
    ]
  },
  "recommendations": [
    "Reduce hard acceleration frequency",
    "Maintain constant speed driving",
    "Ensure sufficient following distance"
  ],
  "performanceMetrics": {
    "efficiency": 88.5,
    "safety": 92.0,
    "consistency": 85.2,
    "ecoScore": 82.0
  },
  "generatedAt": "2026-01-13T14:30:00Z"
}

Security and Privacy

Authentication and Authorization

User authentication token required (JWT/OAuth2)
Vehicle access permission verification
Driving data collection consent verification

Data Security

All API communication encrypted with HTTPS/TLS
Security measures when transmitting driving data
Sensitive information stored only on server

Privacy Protection

Explicit consent for driving data collection
Specify data collection purpose
Compliance with data retention period policy
Guarantee right to data deletion upon user request

Access Control

VIN-based vehicle access permission verification
Manage user-specific driving data access permissions
Detect abnormal access patterns

Exception Handling

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

Sensor Error: Sensor error notification, display default values
Data Inaccuracy: Low data reliability notification
GPS Error: Location information error handling

Score Calculation Error: Score calculation failure notification
Insufficient Data: Insufficient analysis data notification
Abnormal Pattern: Abnormal driving pattern detection notification

Test Setup

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

Use Swagger UI for interactive API testing.

Deployment Considerations

App Store Registration

Request driving data collection permissions
Request location information collection permissions
Clear description of real-time data collection

Legal Regulation Compliance

Compliance with personal information protection laws
Mandatory driving data collection consent
Compliance with data retention period policies
Ensure transparency of scoring logic

Vehicle Compatibility

Support various vehicle models
Consider data processing differences by sensor type
Reflect OEM-specific driving data format differences

Driving Habit Analysis API Developer Guide ​

Service Overview ​

Service Features ​

Legal Requirements ​

Key Scenarios ​

Scenario 1: Event Detection During Driving and Data Collection ​

Scenario 2: Driving Score Detailed Query and Analysis ​

Scenario 3: Risky Driving Pattern Detection and Emergency Response ​

Key Features ​

📱 Features to Implement in App ​

1. Driving Score Monitoring ​

2. Driving Records and Analysis ​

3. Competition and Motivation ​

4. Risky Driving Alerts ​

🏢 Features to Implement in Call Center ​

1. Data Collection and Processing ​

2. Scoring System ​

3. Analysis and Reporting ​

4. Emergency Response System ​

5. Data Management ​

Sequence Diagram ​

Driving Habit Analysis System Flow ​

API Endpoints ​

Driving Score Query ​

Driving Score Record Query ​

Driving Analysis Query ​

Data Models ​

Driving Score Information ​

Driving Record Data ​

Driving Score Record Response ​

Driving Analysis Response ​

Security and Privacy ​

Authentication and Authorization ​

Data Security ​

Privacy Protection ​

Access Control ​

Exception Handling ​

Network Related ​

Sensor Related ​

Data Analysis Related ​

Test Setup ​

Deployment Considerations ​

App Store Registration ​

Legal Regulation Compliance ​

Vehicle Compatibility ​

Driving Habit Analysis API Developer Guide

Service Overview

Service Features

Legal Requirements

Key Scenarios

Scenario 1: Event Detection During Driving and Data Collection

Scenario 2: Driving Score Detailed Query and Analysis

Scenario 3: Risky Driving Pattern Detection and Emergency Response

Key Features

📱 Features to Implement in App

1. Driving Score Monitoring

2. Driving Records and Analysis

3. Competition and Motivation

4. Risky Driving Alerts

🏢 Features to Implement in Call Center

1. Data Collection and Processing

2. Scoring System

3. Analysis and Reporting

4. Emergency Response System

5. Data Management

Sequence Diagram

Driving Habit Analysis System Flow

API Endpoints

Driving Score Query

Driving Score Record Query

Driving Analysis Query

Data Models

Driving Score Information

Driving Record Data

Driving Score Record Response

Driving Analysis Response

Security and Privacy

Authentication and Authorization

Data Security

Privacy Protection

Access Control

Exception Handling

Network Related

Sensor Related

Data Analysis Related

Test Setup

Deployment Considerations

App Store Registration

Legal Regulation Compliance

Vehicle Compatibility