Parking Location Check API Developer Guide

Service Overview

The Parking Location service is a telematics service that allows users to remotely check their vehicle's current parking location through mobile apps or web platforms.

Service Features

Real-time vehicle parking location tracking
Parking location history management
Geofence-based parking alerts
Parking duration tracking
Parking location sharing

Legal Requirements

Compliance with Personal Information Protection Act
Explicit consent required for location data collection
Real-time location tracking requires separate consent
Compliance with data retention policies

Key Scenarios

Scenario 1: Parking Location Update Request and Processing

API Flow by Entity:

📱 App (User):

Location Request: Request current parking location
Status Check: Check location update status (in progress/completed)
Location Display: Display current parking location on map

🚗 Vehicle (TCU):

Location Data Collection: Collect GPS coordinates and parking status
Location Data Transmission: Transmit location data to server
Parking Detection: Detect parking status and duration

🏢 Call Center:

Duplicate Request Prevention: Apply duplicate request prevention logic
Command Transmission: Send location update command to vehicle
Data Processing: Process and validate received location data
Geocoding: Convert coordinates to address information
Storage: Store location data with timestamp

Scenario 2: Real-time Parking Location Query

API Flow by Entity:

📱 App (User):

Location Query: Query current parking location
Map Display: Display parking location on interactive map
Address Display: Display detailed address information

🏢 Call Center:

Location Provision: Provide latest parking location
Location Management: Automatic management of parking location information
Data Caching: Efficient caching of location data
Address Resolution: Resolve coordinates to addresses

Scenario 3: Parking Location History Query

API Flow by Entity:

📱 App (User):

History Query: Query parking location history
History Display: Display parking location history on timeline
Pattern Analysis: Display parking pattern analysis

🏢 Call Center:

History Management: Automatic management of parking location history
Pattern Analysis: Analyze parking location patterns
Statistics Generation: Generate parking-related statistics

Scenario 4: Geofence-based Parking Alerts

API Flow by Entity:

📱 App (User):

Geofence Setup: Set up parking geofence
Alert Configuration: Configure parking alert settings
Alert Reception: Receive parking alert notifications

🏢 Call Center:

Geofence Management: Manage parking geofence settings
Alert Generation: Generate parking alert notifications
Push Notifications: Send push notifications to user app

API Flow by Entity:

📱 App (User):

Share Request: Request parking location sharing
Share Link Generation: Generate shareable location link
Share Management: Manage shared location access

🏢 Call Center:

Share Processing: Process parking location sharing requests
Link Generation: Generate secure sharing links
Access Control: Manage shared location access permissions

Scenario 6: Parking Duration Tracking

API Flow by Entity:

📱 App (User):

Duration Query: Query parking duration
Duration Display: Display parking duration information
Alert Setup: Set up parking duration alerts

🏢 Call Center:

Duration Calculation: Calculate parking duration
Duration Management: Manage parking duration tracking
Alert Generation: Generate duration-based alerts

Scenario 7: Real-time Location Events

API Flow by Entity:

📱 App (User):

SSE Connection: Connect to real-time location event stream
Real-time Reception: Receive parking location changes in real-time

🏢 Call Center:

Event Stream Provision: Provide real-time location event stream
Event Transmission: Transmit location change events in real-time

Key Features

📱 Features to Implement in App

1. Parking Location Query and Monitoring

Location Query: Query current parking location immediately
Map Display: Display parking location on interactive map
Address Display: Display detailed address information
Real-time Updates: Real-time parking location updates
Location Sharing: Share parking location with others

2. Parking Location History

History Query: Query parking location history
Timeline Display: Display parking history on timeline
Pattern Analysis: Display parking pattern analysis
Statistics: Display parking-related statistics

3. Geofence and Alerts

Geofence Setup: Set up parking geofence
Alert Configuration: Configure parking alert settings
Alert Reception: Receive parking alert notifications
Alert Management: Manage alert preferences

4. Parking Duration Tracking

Duration Query: Query parking duration
Duration Display: Display parking duration information
Duration Alerts: Set up parking duration alerts
Duration History: Display parking duration history

5. Real-time Event Reception

SSE Connection: Connect to real-time location event stream
Real-time Reception: Receive parking location changes in real-time
Event Processing: Process and display received events

🏢 Features to Implement in Call Center

1. Parking Location Data Collection System

Data Reception: Receive parking location data in real-time
Data Storage: Secure storage of location data
Location Management: Automatic management of latest location
Quality Management: Manage location data quality and accuracy
Data Validation: Validate location data validity

2. Location History Management System

History Collection: Automatic collection of parking location history
History Management: Automatic management of location history
Pattern Analysis: Automatic analysis of parking location patterns
Statistics Generation: Automatic generation of parking-related statistics

3. Geofence and Alert System

Geofence Management: Automatic management of parking geofence
Alert Generation: Automatic generation of parking alert notifications
Push Notifications: Automatic sending of push notifications to user app
Alert Configuration: Management of alert configurations

Share Processing: Process parking location sharing requests
Link Generation: Generate secure sharing links
Access Control: Manage shared location access permissions
Share Management: Manage sharing settings and permissions

5. Duration Tracking System

Duration Calculation: Calculate parking duration automatically
Duration Management: Automatic management of parking duration
Duration Alerts: Generate duration-based alerts
Duration History: Manage parking duration history

6. API Service Management

API Response Processing: Process parking location related API requests
Request Validation: Validate API requests
Performance Monitoring: Monitor API response time and availability
Error Handling: Handle API errors and exceptions
Version Management: Manage API versions and compatibility

7. Security and Privacy

Location Collection Consent: Manage consent for location data collection
Privacy Protection: Protect user location data privacy
Data Security: Secure processing of location data
Audit Logging: Maintain audit logs for location access
Access Control: Manage user-specific location access permissions

8. System Operations and Monitoring

System Status Monitoring: 24/7 monitoring of parking location system
Data Quality Management: Manage location data quality and accuracy
GPS Status Monitoring: Monitor GPS communication status
Exception Handling: Handle network, GPS, data processing exceptions
System Optimization: Optimize location data processing logic

9. Data Analysis and Statistics

Pattern Analysis: Automatic analysis of parking location patterns
Usage Statistics: Automatic generation of location query usage statistics
Service Quality Analysis: Automatic analysis of location service quality
Improvement Recommendations: Automatic generation of service improvement recommendations

Sequence Diagram

Parking Location System Flow

Parking Location

API Endpoints

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

Current Parking Location Query

bash

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

Parking Location History Query

bash

curl -X GET "https://api.ecarus.run/api/v1/information/vehicles/KMHSH81C7LU123456/parking-location/history?limit=10" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

Parking Location Update Request

bash

curl -X POST "https://api.ecarus.run/api/v1/information/vehicles/KMHSH81C7LU123456/parking-location/refresh" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"priority": "HIGH", "timeout": 30}'

Data Models

Parking Location Information Response

json

{
  "vin": "KMHSH81C7LU123456",
  "userId": "user123",
  "timestamp": "2026-01-13T14:30:00Z",
  "location": {
    "latitude": 37.4021,
    "longitude": 127.1087,
    "altitude": 15.2,
    "accuracy": 5.0,
    "heading": 185.5,
    "speed": 0,
    "unit": "KM/H"
  },
  "address": {
    "country": "South Korea",
    "city": "Seoul",
    "district": "Gangnam-gu",
    "street": "Teheran-ro",
    "building": "123",
    "postalCode": "06234"
  },
  "parking": {
    "isParked": true,
    "parkingDuration": 28500,
    "parkingType": "STREET",
    "parkingLocation": {
      "floor": "B2",
      "zone": "A-15",
      "coordinates": {
        "latitude": 37.4021,
        "longitude": 127.1087
      }
    },
    "parkingStartTime": "2026-01-13T06:45:00Z"
  },
  "geofence": {
    "withinGeofence": true,
    "geofenceId": "home-001",
    "geofenceName": "Home",
    "distanceFromCenter": 150,
    "unit": "METERS"
  },
  "lastUpdate": "2026-01-13T14:30:00Z"
}

Parking Location History Response

json

{
  "vin": "KMHSH81C7LU123456",
  "userId": "user123",
  "period": "30d",
  "limit": 10,
  "offset": 0,
  "history": [
    {
      "locationId": "loc-001",
      "timestamp": "2026-01-13T14:30:00Z",
      "location": {
        "latitude": 37.4021,
        "longitude": 127.1087,
        "address": "123 Teheran-ro, Gangnam-gu, Seoul"
      },
      "parking": {
        "isParked": true,
        "parkingDuration": 28500,
        "parkingType": "STREET"
      },
      "geofence": {
        "withinGeofence": true,
        "geofenceName": "Home"
      }
    },
    {
      "locationId": "loc-002",
      "timestamp": "2026-01-12T18:30:00Z",
      "location": {
        "latitude": 37.5665,
        "longitude": 126.9780,
        "address": "100 Sejong-daero, Jongno-gu, Seoul"
      },
      "parking": {
        "isParked": true,
        "parkingDuration": 43200,
        "parkingType": "GARAGE"
      },
      "geofence": {
        "withinGeofence": false,
        "geofenceName": null
      }
    }
  ],
  "total": 45,
  "hasMore": true,
  "nextOffset": 10
}

Parking Location Update Request Response

json

{
  "vin": "KMHSH81C7LU123456",
  "userId": "user123",
  "requestId": "req-001",
  "status": "PROCESSING",
  "priority": "HIGH",
  "timeout": 30,
  "createdAt": "2026-01-13T14:30:00Z",
  "estimatedCompletion": "2026-01-13T14:30:30Z"
}

Security and Privacy

Authentication and Authorization

User authentication token required (JWT/OAuth2)
Vehicle access permission verification
Location query permission confirmation

Data Security

All API communications encrypted with HTTPS/TLS
Secure transmission of location data
Protection of sensitive location information

Privacy Protection

Explicit consent for location data collection
Real-time location tracking requires separate consent
Compliance with data retention policies
Right to data deletion upon user request

Access Control

VIN-based vehicle access permission verification
User-specific location access permission management
Detection of abnormal access patterns

Exception Handling

Connection Failure: Offline mode support, last location caching
Slow Response: Loading indicator, timeout handling
Server Down: Error message display, retry suggestion

GPS Signal Loss: Last known location usage
Low Accuracy: Low accuracy notification
GPS Error: GPS error notification, default location display

Vehicle Moving: Vehicle moving status notification
Location Not Updated: Location update required notification
Invalid Location: Invalid location data handling

Authentication Failure: Re-authentication requirement
Insufficient Permissions: Clear explanation of permission shortage
Location Access Permission: Location access permission shortage 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 location data collection permissions
Request real-time location tracking permissions
Clear description of parking location monitoring

Legal Regulation Compliance

Compliance with Personal Information Protection Act
Explicit consent required for location data collection
Real-time location tracking requires separate consent
Compliance with data retention policies

Vehicle Compatibility

Support for various vehicle models
Support for internal combustion/electric/hybrid vehicles
Consideration of GPS module differences
Consideration of location accuracy differences

Parking Location Check API Developer Guide ​

Service Overview ​

Service Features ​

Legal Requirements ​

Key Scenarios ​

Scenario 1: Parking Location Update Request and Processing ​

Scenario 2: Real-time Parking Location Query ​

Scenario 3: Parking Location History Query ​

Scenario 4: Geofence-based Parking Alerts ​

Scenario 5: Parking Location Sharing ​

Scenario 6: Parking Duration Tracking ​

Scenario 7: Real-time Location Events ​

Key Features ​

📱 Features to Implement in App ​

1. Parking Location Query and Monitoring ​

2. Parking Location History ​

3. Geofence and Alerts ​

4. Parking Duration Tracking ​

5. Real-time Event Reception ​

🏢 Features to Implement in Call Center ​

1. Parking Location Data Collection System ​

2. Location History Management System ​

3. Geofence and Alert System ​

4. Location Sharing System ​

5. Duration Tracking System ​

6. API Service Management ​

7. Security and Privacy ​

8. System Operations and Monitoring ​

9. Data Analysis and Statistics ​

Sequence Diagram ​

Parking Location System Flow ​

API Endpoints ​

Current Parking Location Query ​

Parking Location History Query ​

Parking Location Update Request ​

Data Models ​

Parking Location Information Response ​

Parking Location History Response ​

Parking Location Update Request Response ​

Security and Privacy ​

Authentication and Authorization ​

Data Security ​

Privacy Protection ​

Access Control ​

Exception Handling ​

Network Related ​

GPS Related ​

Location Related ​

Permission Related ​

Test Setup ​

Deployment Considerations ​

App Store Registration ​

Legal Regulation Compliance ​

Vehicle Compatibility ​

Parking Location Check API Developer Guide

Service Overview

Service Features

Legal Requirements

Key Scenarios

Scenario 1: Parking Location Update Request and Processing

Scenario 2: Real-time Parking Location Query

Scenario 3: Parking Location History Query

Scenario 4: Geofence-based Parking Alerts

Scenario 5: Parking Location Sharing

Scenario 6: Parking Duration Tracking

Scenario 7: Real-time Location Events

Key Features

📱 Features to Implement in App

1. Parking Location Query and Monitoring

2. Parking Location History

3. Geofence and Alerts

4. Parking Duration Tracking

5. Real-time Event Reception

🏢 Features to Implement in Call Center

1. Parking Location Data Collection System

2. Location History Management System

3. Geofence and Alert System

4. Location Sharing System

5. Duration Tracking System

6. API Service Management

7. Security and Privacy

8. System Operations and Monitoring

9. Data Analysis and Statistics

Sequence Diagram

Parking Location System Flow

API Endpoints

Current Parking Location Query

Parking Location History Query

Parking Location Update Request

Data Models

Parking Location Information Response

Parking Location History Response

Parking Location Update Request Response

Security and Privacy

Authentication and Authorization

Data Security

Privacy Protection

Access Control

Exception Handling

Network Related

GPS Related

Location Related

Permission Related

Test Setup

Deployment Considerations

App Store Registration

Legal Regulation Compliance

Vehicle Compatibility