지오펜싱(Geofencing) API 개발자 가이드

서비스 개요

지오펜싱(Geofencing) 서비스는 특정 지리적 영역(Geofence)을 기준으로 차량의 위치 변화를 감지하여 알림, 기록 및 안전 관리 기능을 제공하는 텔레매틱스 서비스입니다.

서비스 특징

가상 지리 경계 영역 설정
차량 위치 진입/이탈 자동 감지
아동 차량 방치 사고 예방 기능
실시간 안전 관리 지원
등하교 상황 확인

법적 요구사항

개인정보 보호법 준수
위치정보 수집 동의 필수
아동 보호 관련 규정 준수
데이터 보유 기간 정책 준수

주요 시나리오

시나리오 1: 지오펜스 설정

엔티티별 API 흐름:

📱 앱 (사용자):

지오펜스 설정: 지오펜스 영역 등록 또는 업데이트
지오펜스 조회: 설정된 지오펜스 목록 확인

🚗 차량 (TCU):

위치 전송: 주기적으로 차량 위치 정보 전송
상태 보고: 현재 위치 상태를 ECARUS 서버에 보고

🏢 콜센터:

이벤트 모니터링: 실시간 진입/이탈 이벤트 모니터링
이력 확인: 지오펜스 방문 기록 확인

주요 기능

앱 기능

지오펜스 설정: 지오펜스 영역 등록 또는 업데이트
지오펜스 조회: 설정된 지오펜스 목록 확인
실시간 모니터링: SSE 스트림을 통한 실시간 알림 수신
이력 조회: 지오펜스 방문 기록 확인
위치 상태: 차량 원격 정보 수신

콜센터 기능

지오펜스 관리: 전체 지오펜스 영역 관리 및 전체 지오펜스 영역 업데이트
알림 모니터링: 실시간 위반 상황 모니터링
이력 관리: 지오펜스 방문 이력 관리
비상 지원: 위반 상황 감지 시 티켓 자동 생성

시퀀스 다이어그램

지오펜싱 시스템 흐름

지오펜싱

플랫폼 연동 고려사항

위치 데이터 처리

실시간 위치 스트림 처리
GPS 데이터 기반 위치 수집
위치 전송 주기 최적화
위치 정확도 관리

API 엔드포인트

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

지오펜스 관리

지오펜스 목록 조회

bash

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

지오펜스 설정 업데이트

bash

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": "강남중학교",
               "type": "school",
               "center": {"latitude": 37.5665, "longitude": 126.9780},
               "radius": 300,
               "enabled": true,
               "rules": {"enterNotification": true, "exitNotification": true}
             }
           ]
         }'

지오펜스 실시간 이벤트 수신 (SSE)

참고: 브라우저를 통해 접속하거나 전용 SSE 클라이언트 사용 권장

bash

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

데이터 모델

지오펜스 영역 설정

json

{
  "id": "unique_geofence_id",
  "name": "지오펜스 명칭",
  "type": "school|home|work|custom",
  "center": {
    "latitude": 37.5665,
    "longitude": 126.9780
  },
  "radius": 300,
  "enabled": true,
  "rules": {
    "enterNotification": true,
    "exitNotification": true
  }
}

지오펜스 이벤트

json

{
  "eventId": "geofence-event-67890",
  "vin": "KMHSH81C7LU123456",
  "timestamp": "2026-01-13T08:30:00Z",
  "eventType": "ENTER_ZONE",
  "geofenceId": "geofence-12345",
  "geofenceName": "강남중학교",
  "location": {
    "latitude": 37.5665,
    "longitude": 126.9780,
    "address": "2 Taepyeong-ro, Jung-gu, Seoul"
  },
  "message": "차량이 학교 존에 진입했습니다.",
  "severity": "INFO"
}

지오펜스 방문 이력

json

{
  "visitId": "visit-001",
  "vin": "KMHSH81C7LU123456",
  "geofenceId": "geofence-12345",
  "geofenceName": "강남중학교",
  "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"
  }
}

인증 및 보안

인증 요구사항

사용자 인증 토큰 필요 (JWT/OAuth2)
차량 접근 권한 확인
지오펜스 설정 권한 확인
위치정보 수집 동의

데이터 보안

모든 API 통신은 HTTPS/TLS 암호화
위치 데이터 전송 시 보안 조치
민감 위치 정보는 서버에만 저장
위치 정보 암호화 처리

프라이버시 보호

위치정보 수집 동의 필수
위치 데이터 목적 명시
데이터 보유 기간 정책 준수
사용자 위치 데이터 삭제 권한 보장

접근 제어

VIN 기반 차량 접근 권한 확인
사용자별 지오펜스 접근 관리
이상 접근 패턴 감지
지오펜스 공유 권한 관리

예외 처리

위치 관련

GPS 신호 상실: 마지막 확인 위치 사용 및 재연결 시도
위치 정확도 오류: GPS 정확도 보정 알고리즘 적용
실내 주차: 실내 위치 부정확 알림
위치 데이터 지연: 실시간 위치 처리 최적화

지오펜스 관련

지오펜스 중첩: 다중 지오펜스 중첩 처리 로직
경계 모호성: 경계 판별 오류 방지
지오펜스 설정 오류: 지오펜스 설정 유효성 검사
이벤트 생성 실패: 이벤트 생성 재시도 메커니즘

네트워크 관련

연결 실패: 오프라인 모드 지원 및 데이터 저장
응답 지연: 로딩 인디케이터 및 타임아웃 처리
서버 다운: 에러 메시지 표시 및 재시도 제안

알림 관련

알림 전송 실패: 다중 채널 알림 전송
수신자 무응답: 에스컬레이션 정책 적용
오알림: 오탐 방지 알고리즘 강화

테스트 설정

Base URL: https://api.ecarus.run/api/v1/childcare
인증 토큰: sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d
샘플 VIN: KMHSH81C7LU123456

대화형 API 테스트를 위해 Swagger UI를 사용하십시오.

배포 고려사항

앱 스토어 등록

위치정보 수집 권한 요청
푸시 알림 권한 요청
지오펜싱 기능에 대한 명확한 설명

법규 준수

개인정보 보호법 준수
위치정보 수집 동의 필수
아동 보호 관련 규정 준수
데이터 보유 기간 정책 준수

위치 정확성

GPS 신호 최적화
위치 정확도 관리
실내/외 위치 구분
위치 데이터 품질 관리

성능 최적화

실시간 위치 처리 최적화
지오펜스 판별 알고리즘 최적화
대규모 지오펜스 관리 지원
이벤트 전송 효율성 개선

지오펜싱(Geofencing) API 개발자 가이드 ​

서비스 개요 ​

서비스 특징 ​

법적 요구사항 ​

주요 시나리오 ​

시나리오 1: 지오펜스 설정 ​

주요 기능 ​

앱 기능 ​

콜센터 기능 ​

시퀀스 다이어그램 ​

지오펜싱 시스템 흐름 ​

플랫폼 연동 고려사항 ​

위치 데이터 처리 ​

지오펜스 판별 로직 ​

아동 탑승 감지 ​

알림 시스템 ​

API 엔드포인트 ​

지오펜스 관리 ​

지오펜스 목록 조회 ​

지오펜스 설정 업데이트 ​

지오펜스 실시간 이벤트 수신 (SSE) ​

데이터 모델 ​

지오펜스 영역 설정 ​

지오펜스 이벤트 ​

지오펜스 방문 이력 ​

인증 및 보안 ​

인증 요구사항 ​

데이터 보안 ​

프라이버시 보호 ​

접근 제어 ​

예외 처리 ​

위치 관련 ​

지오펜스 관련 ​

네트워크 관련 ​

알림 관련 ​

테스트 설정 ​

배포 고려사항 ​

앱 스토어 등록 ​

법규 준수 ​

위치 정확성 ​

성능 최적화 ​

지오펜싱(Geofencing) API 개발자 가이드

서비스 개요

서비스 특징

법적 요구사항

주요 시나리오

시나리오 1: 지오펜스 설정

주요 기능

앱 기능

콜센터 기능

시퀀스 다이어그램

지오펜싱 시스템 흐름

플랫폼 연동 고려사항

위치 데이터 처리

지오펜스 판별 로직

아동 탑승 감지

알림 시스템

API 엔드포인트

지오펜스 관리

지오펜스 목록 조회

지오펜스 설정 업데이트

지오펜스 실시간 이벤트 수신 (SSE)

데이터 모델

지오펜스 영역 설정

지오펜스 이벤트

지오펜스 방문 이력

인증 및 보안

인증 요구사항

데이터 보안

프라이버시 보호

접근 제어

예외 처리

위치 관련

지오펜스 관련

네트워크 관련

알림 관련

테스트 설정

배포 고려사항

앱 스토어 등록

법규 준수

위치 정확성

성능 최적화