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 공식을 사용하여 정확한 거리 계산을 수행합니다.

데이터 출처 및 라이센스 #

공공데이터 출처 #

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

• 서비스명: 기상청 단기예보 ((구) 동네예보) 조회서비스
• 공공데이터포털: https://www.data.go.kr/tcs/dss/selectApiDataDetailView.do?publicDataPk=15084084
• 제공기관: 기상청
• 데이터 ID: 15084084
• 이용허락범위: 저작자표시, 공공저작물 출처표시

패키지 라이센스 #

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

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

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

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

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

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