Geofencing API Developer Guide

Service Overview

Geofencing Service is a telematics service that detects vehicle location changes based on specific geographical areas (Geofence) to provide alerts, recording, and safety management functions.

Service Features

• Virtual geographical boundary area setting
• Automatic vehicle location entry/exit detection
• Child left-behind accident prevention function
• Real-time safety management support
• School commute situation verification

Legal Requirements

• Compliance with personal information protection laws
• Mandatory location information collection consent
• Compliance with child protection-related regulations
• Compliance with data retention period policies

Key Scenarios

Scenario 1: Geofence Setting

API Flow by Entity:

📱 App (User):

1. Set Geofence: Register or update geofence areas
2. Query Geofences: Check configured geofence list

🚗 Vehicle (TCU):

1. Location Transmission: Periodically transmit vehicle location information
2. Status Report: Report current location status to ECARUS server

🏢 Call Center:

1. Event Monitoring: Monitor real-time entry/exit events
2. History Check: Check geofence visit records

Key Features

App Features

• Geofence Setting: Register or update geofence areas
• Geofence Query: Check configured geofence list
• Real-time Monitoring: Receive real-time alerts via SSE stream
• History Query: Check geofence visit records
• Location Status: Receive vehicle remote information

Call Center Features

• Geofence Management: Manage entire geofence areas and Manage entire geofence areas
• Alert Monitoring: Real-time violation situation monitoring
• History Management: Manage geofence visit history
• Emergency Support: Automatically generate ticket when violation detected

Sequence Diagram

Geofencing System Flow

Platform Integration Considerations

Location Data Processing

• Real-time location stream processing
• GPS data-based location collection
• Location transmission period optimization
• Location accuracy management

Geofence Determination Logic

• Server-based Geofence determination
• False detection prevention with Hysteresis application
• Multi-Geofence overlap processing
• Real-time event generation

Child Boarding Detection

• Utilize vehicle internal sensor data
• Combine multiple detection methods
• False detection prevention algorithms
• Status change event processing

Alert System

• Real-time alert transmission
• Multiple recipient support
• Alert priority management
• Alert history management

API Endpoints

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

Geofence Management

Geofence List Query

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

Geofence Configuration Update

curl -X POST "https://api.ecarus.run/api/v1/childcare/vehicles/KMHSH81C7LU123456/geofence/config" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{
           "geofences": [
             {
               "id": "school_002",
               "name": "Gangnam Middle School",
               "type": "school",
               "center": {"latitude": 37.5665, "longitude": 126.9780},
               "radius": 300,
               "enabled": true,
               "rules": {"enterNotification": true, "exitNotification": true}
             }
           ]
         }'

Geofence Real-time Event Reception (SSE)

Note: Recommend accessing via browser or using dedicated SSE client

curl -N -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     "https://api.ecarus.run/api/v1/childcare/vehicles/KMHSH81C7LU123456/geofence/events"

Data Models

Geofence Area Setting

{
  "id": "unique_geofence_id",
  "name": "Geofence name",
  "type": "school|home|work|custom",
  "center": {
    "latitude": 37.5665,
    "longitude": 126.9780
  },
  "radius": 300,
  "enabled": true,
  "rules": {
    "enterNotification": true,
    "exitNotification": true
  }
}

Geofence Event

{
  "eventId": "geofence-event-67890",
  "vin": "KMHSH81C7LU123456",
  "timestamp": "2026-01-13T08:30:00Z",
  "eventType": "ENTER_ZONE",
  "geofenceId": "geofence-12345",
  "geofenceName": "Gangnam Middle School",
  "location": {
    "latitude": 37.5665,
    "longitude": 126.9780,
    "address": "2 Taepyeong-ro, Jung-gu, Seoul"
  },
  "message": "Vehicle has entered school zone.",
  "severity": "INFO"
}

Geofence Visit History

{
  "visitId": "visit-001",
  "vin": "KMHSH81C7LU123456",
  "geofenceId": "geofence-12345",
  "geofenceName": "Gangnam Middle School",
  "enterTime": "2026-01-13T08:30:00Z",
  "exitTime": "2026-01-13T15:45:00Z",
  "duration": 435,
  "location": {
    "latitude": 37.5665,
    "longitude": 126.9780,
    "address": "2 Taepyeong-ro, Jung-gu, Seoul"
  }
}

Authentication and Security

Authentication Requirements

• User authentication token required (JWT/OAuth2)
• Vehicle access permission verification
• Geofence setting permission verification
• Location information collection consent

Data Security

• All API communication encrypted with HTTPS/TLS
• Security measures when transmitting location data
• Sensitive location information stored only on server
• Location information encryption processing

Privacy Protection

• Mandatory location information collection consent
• Location data purpose specification
• Data retention period policy compliance
• User right to location data deletion guarantee

Access Control

• VIN-based vehicle access permission verification
• User-specific geofence access management
• Abnormal access pattern detection
• Geofence sharing permission management

Exception Handling

Location Related

• GPS Signal Loss: Use last known location and reconnection retry
• Location Accuracy Error: GPS accuracy correction algorithm application
• Indoor Parking: Indoor location inaccuracy notification
• Location Data Delay: Real-time location processing optimization

Geofence Related

• Geofence Overlap: Multi-geofence overlap processing logic
• Boundary Ambiguity: Boundary determination error prevention
• Geofence Setting Error: Geofence configuration validation
• Event Generation Failure: Event generation retry mechanism

Network Related

• Connection Failure: Offline mode support and data storage
• Slow Response: Loading indicator and timeout handling
• Server Down: Error message display and retry suggestion

Alert Related

• Alert Transmission Failure: Multi-channel alert transmission
• Recipient Non-response: Escalation policy application
• False Alert: False detection prevention algorithm enhancement

Test Setup

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

Use Swagger UI for interactive API testing.

Deployment Considerations

App Store Registration

• Request location information collection permissions
• Request push notification permissions
• Clear explanation of geofencing functionality

Legal Regulation Compliance

• Compliance with personal information protection laws
• Mandatory location information collection consent
• Compliance with child protection-related regulations
• Compliance with data retention period policies

Location Accuracy

• GPS signal optimization
• Location accuracy management
• Indoor/outdoor location distinction
• Location data quality control

Performance Optimization

• Real-time location processing optimization
• Geofence determination algorithm optimization
• Large-scale geofence management support
• Event transmission efficiency improvement