Naeil Location Package

현재 GPS 위치를 조회하고 가장 가까운 한국 행정구역 주소(1단계, 2단계, 3단계)를 자동으로 매칭하는 고성능 Flutter 패키지입니다.

주요 기능

  • 📍 현재 위치 조회: 정확한 GPS 좌표(위도, 경도) 조회
  • 🏠 주소 매칭: 약 34,000개의 행정구역 데이터베이스에서 가장 가까운 한국 주소 자동 검색
  • ⚡ 고성능 최적화:
    • 공간 인덱싱: 격자 기반 검색 알고리즘으로 검색 공간을 99% 축소
    • 지연 로딩: 필요할 때만 JSON 데이터 로드
    • 캐싱: 자주 접근하는 위치에 대한 LRU 캐시
  • 🌡️ 날씨 격자 좌표 지원: 기상청(KMA) API와 호환되는 격자 X/Y 좌표 제공

설치

프로젝트의 pubspec.yaml 파일에 다음을 추가하세요:

dependencies:
  naeil_location:

설정

Android

android/app/src/main/AndroidManifest.xml 파일에 다음 권한을 추가하세요:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- 정밀 위치(GPS) 접근 권한 -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <!-- 대략적 위치(네트워크) 접근 권한 -->
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

    <application ...>
       ...
    </application>
</manifest>

iOS

ios/Runner/Info.plist 파일에 다음 키를 추가하세요:

<key>NSLocationWhenInUseUsageDescription</key>
<string>이 앱은 현재 주소를 표시하기 위해 위치 정보 접근이 필요합니다.</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>이 앱은 백그라운드에서 현재 주소를 표시하기 위해 위치 정보 접근이 필요합니다.</string>

사용법

현재 위치 및 주소 조회

가장 간단한 방법으로 현재 위치와 주소를 조회합니다:

import 'package:naeil_location/naeil_location.dart';

try {
  final data = await NaeilLocation.getCurrentLocationWithAddress();

  print('주소: ${data.fullAddress}'); // 서울특별시 종로구 청운효자동
  print('좌표: ${data.latitude}, ${data.longitude}');
  print('날씨 격자: ${data.gridX}, ${data.gridY}');

} catch (e) {
  print('오류: $e');
}

좌표만 조회

GPS 좌표만 필요한 경우:

final coords = await NaeilLocation.getCurrentLocation();
print('위도: ${coords.latitude}, 경도: ${coords.longitude}');

좌표로 주소 찾기

이미 좌표가 있고 주소를 찾고 싶은 경우:

final data = await NaeilLocation.findNearestAddress(
  latitude: 37.5665,
  longitude: 126.9780,
);
print('주소: ${data.fullAddress}');

실시간 위치 스트림

위치 변경을 추적하고 업데이트된 주소를 받습니다:

StreamBuilder<LocationData>(
  stream: NaeilLocation.getLocationStream(),
  builder: (context, snapshot) {
    if (snapshot.hasData) {
      return Text(snapshot.data!.fullAddress);
    }
    return CircularProgressIndicator();
  },
)

에러 처리

패키지는 다양한 에러 상황에 대해 구체적인 예외를 발생시킵니다:

  • LocationPermissionDeniedException: 사용자가 위치 권한을 거부한 경우
  • LocationServiceDisabledException: GPS/위치 서비스가 비활성화된 경우
  • AddressNotFoundException: 좌표에 해당하는 주소를 찾을 수 없는 경우
  • LocationTimeoutException: GPS 신호 타임아웃

성능

  • 메모리 사용량: 로드된 JSON 데이터 기준 약 5-10MB
  • 검색 속도: 초기 로드 후 쿼리당 약 5-20ms
  • 최적화: 격자 좌표로 필터링된 인근 후보에 대해서만 Haversine 공식을 사용하여 정확한 거리 계산을 수행합니다.

데이터 출처 및 라이센스

공공데이터 출처

본 패키지에서 사용하는 한국 행정구역 주소 데이터는 다음 공공데이터를 기반으로 합니다:

패키지 라이센스

본 패키지는 크리에이티브 커먼즈 저작자표시 4.0 국제 라이선스 (CC BY 4.0) 하에 배포됩니다.

CC BY (저작자표시) 라이선스 조건:

  • ✅ 복사 및 배포 가능 (저작자 및 출처 표시 필수)
  • ✅ 상업적 이용 가능
  • ✅ 변경 및 2차 저작물 제작 가능 (원저작자 및 출처 표시 필수)
  • ✅ 2차 저작물의 라이선스 자유 선택 가능

자세한 내용은 LICENSE 파일을 참조하거나 크리에이티브 커먼즈 라이선스를 확인하세요.

공공데이터 이용 시 주의사항

본 패키지를 사용하거나 배포할 때는 위 공공데이터의 출처를 명시해야 합니다. 공공데이터포털의 이용허락범위에 따라 저작자표시 및 출처표시가 필요합니다.

Libraries

naeil_location