Remote Climate Control API Developer Guide

Service Overview

Remote Climate Control is a telematics service that allows users to remotely control the vehicle's HVAC system through a mobile app before boarding, pre-conditioning the interior temperature to a comfortable state.

Service Features

Pre-conditioning interior temperature before boarding
Pre-cooling in summer and pre-heating in winter
Improved electric vehicle battery efficiency and extended driving range
Battery protection with automatic shutdown policy
Independent HVAC system operation without engine start (EV/HEV)

Legal Requirements

Security policy required due to vehicle control features
Compliance with personal information protection laws
Application of location-based restriction policies
Command Rate Limit application

Key Scenarios

Scenario 1: Remote Climate Control Start and Safety Verification

API Flow by Entity:

📱 App (User):

Climate Start Request: Request remote climate start
Response Reception: Receive 202 Accepted response
Result Notification: Receive success/failure results via push notification
Status Check: Check status if successful, check error message if failed

🚗 Vehicle (TCU):

Command Reception: Receive climate start command from server
Safety Verification: Check safety conditions like door open, battery level
HVAC Control: Start HVAC system if safety conditions pass
Result Transmission: Transmit execution results to server (including success/failure codes)

🏢 Call Center:

Command Processing: Process climate start command
Status Management: Automatic command status management (PENDING → SUCCESS/FAIL)
Result Processing: Process results received from vehicle
Error Mapping: Convert error codes to user-friendly messages
History Storage: Automatic storage of command execution history
Notification Transmission: Transmit results via push notification

Scenario 2: Climate Status Query and Monitoring

API Flow by Entity:

📱 App (User):

Status Query: Immediate climate status query
Status Display: Display current climate status information

🏢 Call Center:

Status Provision: Provide latest climate status
Status Management: Automatic climate status information management

Scenario 3: Climate Control Cancellation and Stop

API Flow by Entity:

📱 App (User):

Cancellation Request: Request climate control cancellation
Result Confirmation: Confirm cancellation success message

🚗 Vehicle (TCU):

Cancellation Command Reception: Receive cancellation command from server
HVAC Stop: Immediately stop HVAC system
Result Transmission: Transmit cancellation results to server

🏢 Call Center:

Cancellation Processing: Process cancellation command
Command Transmission: Transmit cancellation command to vehicle
History Storage: Automatic cancellation history storage

Scenario 4: Climate Control History Query

API Flow by Entity:

🏢 Call Center:

History Query: Query climate control history
History Provision: Provide control history information by period

Scenario 5: Climate Environment Settings Management

API Flow by Entity:

📱 App (User):

Settings Query: Query climate environment settings
Settings Update: Update environment settings
Result Confirmation: Confirm settings update success

🏢 Call Center:

Settings Management: Automatic environment settings management and Update environment settings
Settings Storage: Secure storage of user environment settings

Scenario 6: Climate System Diagnostics

API Flow by Entity:

🏢 Call Center:

Diagnostics Query: Query HVAC system diagnostics
Diagnostics Information Provision: Provide system status, component status, last service information

Key Features

📱 Features to Implement in App

1. Remote Climate Control Function

Climate Start: Request remote climate start
Climate Cancellation: Request climate control cancellation
Status Query: Immediate climate status query
Result Notification: Receive climate control success/failure push notifications

2. Environment Settings Management Function

Settings Query: Query climate environment settings
Settings Update: Update environment settings
Personalization: Manage personal settings like target temperature, mode, fan speed

3. Status Monitoring Function

Real-time Status: Real-time display of climate status
Error Handling: User-friendly error message display on failure
Safety Verification: Check safety status like door open, low battery

🏢 Features to Implement in Call Center

1. Climate Control Command Processing System

Command Processing: Process climate start command
Cancellation Processing: Process climate cancellation command
Command Queue: Automatic command request queue management
Command Routing: Automatic command routing to vehicle
Status Management: Automatic command status management (PENDING → SUCCESS/FAIL)

2. Safety Verification System

Safety Condition Check: Automatic check of safety conditions like door open, battery level
Error Handling: Generate appropriate error codes when safety conditions are violated
Error Mapping: Convert technical error codes to user-friendly messages
Result Transmission: Transmit verification results to vehicle and app

3. History Management System

History Storage: Automatic climate control history storage
History Query: Provide control history query function by period
Statistics Generation: Automatic climate usage statistics generation
Analysis Reporting: Generate climate usage pattern analysis reports

4. Environment Settings Management System

Settings Management: Automatic user environment settings management and Update environment settings
Settings Storage: Secure storage of personalized climate settings
Settings Synchronization: Settings synchronization between vehicle and app

5. Diagnostics System

System Diagnostics: Automatic HVAC system diagnostics
Component Status Monitoring: Monitor component status like compressor, fan, sensors
Service History Management: Manage last service information
Diagnostics Reporting: Provide detailed diagnostics information

6. API Service Management

API Response Processing: Process climate control related API responses
Request Verification: Verify API request validity
Performance Monitoring: Monitor API response time and availability
Error Handling: Handle API errors and exception situations
Version Management: API version management and compatibility maintenance

7. Security and Personal Information Protection

Climate Control Consent: Manage consent for climate control function usage
Personal Information Protection: Protect user climate settings personal information
Data Security: Secure processing of climate control data
Audit Log: Climate control access and processing audit logs
Permission Management: Manage user-specific climate control access permissions

Sequence Diagram

Remote Climate Control System Flow

Remote Climate Control

API Endpoints

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

Climate Control Start

bash

curl -X POST "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/climate/start" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"targetTemperature": 22.5, "mode": "AUTO", "fanSpeed": "MEDIUM", "duration": 1800}'

Climate Control Status Query

bash

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

Climate Control Cancellation

bash

curl -X POST "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/climate/cancel" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"reason": "User requested cancellation"}'

Climate Control Stop

bash

curl -X POST "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/climate/stop" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"reason": "Emergency stop", "force": false}'

Climate Control History Query

bash

curl -X GET "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/climate/history?period=24h&limit=50" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

Climate Control Environment Settings Query

bash

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

Climate Control Environment Settings Update

bash

curl -X PUT "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/climate/preferences" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"targetTemperature": 22.0, "mode": "AUTO", "fanSpeed": "MEDIUM", "airCirculation": "AUTO", "ecoMode": false}'

Climate Control Diagnostics Information Query

bash

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

Climate Control Real-time Update Reception (SSE)

Note: Recommended to access via browser or use a dedicated SSE client

bash

curl -X GET "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/climate/updates/stream" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Accept: text/event-stream"

Data Models

Climate Control Start Request

json

{
  "userId": "user123",
  "targetTemperature": 22.5,
  "mode": "AUTO",
  "fanSpeed": "MEDIUM",
  "airCirculation": "AUTO",
  "ecoMode": false,
  "duration": 1800,
  "reason": "Pre-cooling before departure",
  "priority": "NORMAL"
}

Climate Control Start Response

json

{
  "commandId": "cmd-uuid-12345",
  "vin": "KMHSH81C7LU123456",
  "userId": "user123",
  "status": "PENDING",
  "estimatedDuration": 1800,
  "batteryImpact": {
    "estimatedConsumption": 2.5,
    "unit": "kWh",
    "currentSOC": 75.5,
    "estimatedSOCAfter": 73.0
  },
  "timestamp": "2026-01-12T08:30:00Z",
  "expiresAt": "2026-01-12T08:35:00Z"
}

Climate Control Status Response

json

{
  "vin": "KMHSH81C7LU123456",
  "commandId": "cmd-uuid-12345",
  "userId": "user123",
  "isRunning": true,
  "currentTemperature": 18.5,
  "targetTemperature": 22.0,
  "mode": "AUTO",
  "fanSpeed": "MEDIUM",
  "airCirculation": "AUTO",
  "ecoMode": false,
  "remainingTime": 1500,
  "elapsedTime": 300,
  "batterySOC": 75.5,
  "batteryImpact": {
    "consumed": 0.5,
    "unit": "kWh",
    "currentSOC": 75.5,
    "estimatedSOCAfter": 73.0
  },
  "hvacSystemStatus": "NORMAL",
  "timestamp": "2026-01-12T08:45:00Z"
}

Climate Control Cancellation/Stop Request

json

{
  "commandId": "cmd-uuid-12345",
  "reason": "User requested cancellation",
  "force": false,
  "userId": "user123"
}

Climate Control History Request

json

{
  "period": "24h",
  "limit": 50
}

Climate Control History Response

json

{
  "vin": "KMHSH81C7LU123456",
  "userId": "user123",
  "history": [
    {
      "commandId": "cmd-uuid-12345",
      "startTime": "2026-01-12T08:30:45Z",
      "endTime": "2026-01-12T09:00:00Z",
      "duration": 1745,
      "status": "COMPLETED",
      "targetTemperature": 22.5,
      "mode": "AUTO",
      "fanSpeed": "MEDIUM",
      "airCirculation": "AUTO",
      "ecoMode": false,
      "batteryImpact": {
        "consumed": 2.3,
        "unit": "kWh",
        "startSOC": 75.5,
        "endSOC": 73.2
      },
      "reason": "Pre-cooling before departure",
      "success": true
    }
  ],
  "total": 1,
  "pagination": {
    "page": 1,
    "limit": 50,
    "hasMore": false
  }
}

Climate Control Environment Settings Response

json

{
  "vin": "KMHSH81C7LU123456",
  "userId": "user123",
  "preferences": {
    "targetTemperature": 22.0,
    "mode": "AUTO",
    "fanSpeed": "MEDIUM",
    "airCirculation": "AUTO",
    "ecoMode": false,
    "defaultDuration": 1800,
    "maxDuration": 3600,
    "autoStart": {
      "enabled": true,
      "schedule": [
        {
          "dayOfWeek": "MONDAY",
          "time": "08:00",
          "targetTemperature": 22.0,
          "duration": 900
        }
      ]
    },
    "notifications": {
      "completion": true,
      "lowBattery": true,
      "error": true
    }
  },
  "updatedTime": "2026-01-12T10:00:00Z"
}

Climate Control Diagnostics Response

json

{
  "vin": "KMHSH81C7LU123456",
  "userId": "user123",
  "hvacSystemStatus": "NORMAL",
  "overallHealth": 96.5,
  "components": [
    {
      "id": "COMP_001",
      "name": "Compressor",
      "status": "ACTIVE",
      "health": 95,
      "temperature": 45.2,
      "pressure": 120.5,
      "lastMaintenance": "2025-06-15T00:00:00Z",
      "nextMaintenance": "2026-06-15T00:00:00Z",
      "warnings": []
    },
    {
      "id": "BLOWER_001",
      "name": "Blower Motor",
      "status": "ACTIVE",
      "health": 98,
      "speed": 1500,
      "voltage": 12.3,
      "lastMaintenance": "2025-08-20T00:00:00Z",
      "nextMaintenance": "2026-08-20T00:00:00Z",
      "warnings": []
    },
    {
      "id": "FILTER_001",
      "name": "Cabin Air Filter",
      "status": "ACTIVE",
      "health": 85,
      "contaminationLevel": 15,
      "lastReplacement": "2025-03-10T00:00:00Z",
      "nextReplacement": "2026-03-10T00:00:00Z",
      "warnings": [
        {
          "code": "FILTER_REPLACEMENT_SOON",
          "message": "Filter replacement recommended within 3 months",
          "severity": "LOW"
        }
      ]
    }
  ],
  "sensors": [
    {
      "id": "TEMP_IN_001",
      "name": "Interior Temperature Sensor",
      "status": "ACTIVE",
      "value": 18.5,
      "unit": "°C",
      "calibration": "VALID"
    },
    {
      "id": "TEMP_OUT_001",
      "name": "Exterior Temperature Sensor",
      "status": "ACTIVE",
      "value": 12.3,
      "unit": "°C",
      "calibration": "VALID"
    }
  ],
  "errors": [],
  "warnings": [
    {
      "code": "FILTER_REPLACEMENT_SOON",
      "message": "Cabin air filter replacement recommended",
      "severity": "LOW",
      "component": "FILTER_001"
    }
  ],
  "lastCheck": "2026-01-12T08:30:00Z",
  "nextCheck": "2026-01-19T08:30:00Z"
}

Climate Control Real-time Update Reception (SSE)

json

{
  "type": "CLIMATE_STATUS_UPDATE",
  "vin": "KMHSH81C7LU123456",
  "userId": "user123",
  "commandId": "cmd-uuid-12345",
  "timestamp": "2026-01-12T08:45:00Z",
  "data": {
    "isRunning": true,
    "currentTemperature": 18.5,
    "targetTemperature": 22.0,
    "mode": "AUTO",
    "fanSpeed": "MEDIUM",
    "airCirculation": "AUTO",
    "ecoMode": false,
    "remainingTime": 1500,
    "elapsedTime": 300,
    "batterySOC": 75.5,
    "batteryImpact": {
      "consumed": 0.5,
      "unit": "kWh",
      "currentSOC": 75.5,
      "estimatedSOCAfter": 73.0
    },
    "hvacSystemStatus": "NORMAL",
    "alerts": []
  }
}

Security and Privacy

Authentication and Authorization

User authentication token required (JWT/OAuth2)
Vehicle access permission verification
Climate control permission verification

Data Security

All API communication encrypted with HTTPS/TLS
Command Signing to prevent command forgery
mTLS-based communication security

Privacy Protection

Explicit consent for vehicle status information collection
Specify purpose of location information collection
Compliance with command execution history retention period policy

Access Control

VIN-based vehicle access permission verification
Command Rate Limit application
Location-based restriction policy

Exception Handling

Connection Failure: Support offline mode, cache last status
Slow Response: Loading indicator, timeout handling
Server Down: Display error message, suggest retry

Vehicle Offline: Notify command transmission failure, queue processing
Low Battery: Notify execution impossibility, recommend charging
Vehicle Unlocked: Notify security impossibility

Command Failure: Clearly display failure reasons
Partial Success: Detailed guidance when only some functions operate
Automatic Shutdown: Clearly display shutdown reasons

Test Setup

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

Use Swagger UI for interactive API testing.

Deployment Considerations

App Store Registration

Request vehicle control permissions
Clear description of location information collection
Battery optimization related permissions

Legal Regulation Compliance

Compliance with personal information protection laws
Check vehicle control related regulations
Compliance with Command Rate Limit policy

Vehicle Compatibility

Support internal combustion engine/electric/hybrid vehicles
Consider OEM-specific HVAC system differences
Reflect vehicle model-specific function limitations

Remote Climate Control API Developer Guide ​

Service Overview ​

Service Features ​

Legal Requirements ​

Key Scenarios ​

Scenario 1: Remote Climate Control Start and Safety Verification ​

Scenario 2: Climate Status Query and Monitoring ​

Scenario 3: Climate Control Cancellation and Stop ​

Scenario 4: Climate Control History Query ​

Scenario 5: Climate Environment Settings Management ​

Scenario 6: Climate System Diagnostics ​

Key Features ​

📱 Features to Implement in App ​

1. Remote Climate Control Function ​

2. Environment Settings Management Function ​

3. Status Monitoring Function ​

🏢 Features to Implement in Call Center ​

1. Climate Control Command Processing System ​

2. Safety Verification System ​

3. History Management System ​

4. Environment Settings Management System ​

5. Diagnostics System ​

6. API Service Management ​

7. Security and Personal Information Protection ​

Sequence Diagram ​

Remote Climate Control System Flow ​

API Endpoints ​

Climate Control Start ​

Climate Control Status Query ​

Climate Control Cancellation ​

Climate Control Stop ​

Climate Control History Query ​

Climate Control Environment Settings Query ​

Climate Control Environment Settings Update ​

Climate Control Diagnostics Information Query ​

Climate Control Real-time Update Reception (SSE) ​

Data Models ​

Climate Control Start Request ​

Climate Control Start Response ​

Climate Control Status Response ​

Climate Control Cancellation/Stop Request ​

Climate Control History Request ​

Climate Control History Response ​

Climate Control Environment Settings Response ​

Climate Control Diagnostics Response ​

Climate Control Real-time Update Reception (SSE) ​

Security and Privacy ​

Authentication and Authorization ​

Data Security ​

Privacy Protection ​

Access Control ​

Exception Handling ​

Network Related ​

Vehicle Status Related ​

Command Execution Related ​

Test Setup ​

Deployment Considerations ​

App Store Registration ​

Legal Regulation Compliance ​

Vehicle Compatibility ​

Remote Climate Control API Developer Guide

Service Overview

Service Features

Legal Requirements

Key Scenarios

Scenario 1: Remote Climate Control Start and Safety Verification

Scenario 2: Climate Status Query and Monitoring

Scenario 3: Climate Control Cancellation and Stop

Scenario 4: Climate Control History Query

Scenario 5: Climate Environment Settings Management

Scenario 6: Climate System Diagnostics

Key Features

📱 Features to Implement in App

1. Remote Climate Control Function

2. Environment Settings Management Function

3. Status Monitoring Function

🏢 Features to Implement in Call Center

1. Climate Control Command Processing System

2. Safety Verification System

3. History Management System

4. Environment Settings Management System

5. Diagnostics System

6. API Service Management

7. Security and Personal Information Protection

Sequence Diagram

Remote Climate Control System Flow

API Endpoints

Climate Control Start

Climate Control Status Query

Climate Control Cancellation

Climate Control Stop

Climate Control History Query

Climate Control Environment Settings Query

Climate Control Environment Settings Update

Climate Control Diagnostics Information Query

Climate Control Real-time Update Reception (SSE)

Data Models

Climate Control Start Request

Climate Control Start Response

Climate Control Status Response

Climate Control Cancellation/Stop Request

Climate Control History Request

Climate Control History Response

Climate Control Environment Settings Response

Climate Control Diagnostics Response

Climate Control Real-time Update Reception (SSE)

Security and Privacy

Authentication and Authorization

Data Security

Privacy Protection

Access Control

Exception Handling

Network Related

Vehicle Status Related

Command Execution Related

Test Setup

Deployment Considerations

App Store Registration

Legal Regulation Compliance

Vehicle Compatibility