{"id":26157285,"url":"https://github.com/eaceto/opencorelocation","last_synced_at":"2026-06-20T01:31:54.808Z","repository":{"id":281790188,"uuid":"946182303","full_name":"eaceto/OpenCoreLocation","owner":"eaceto","description":"An implementation of CoreLocation for Swift on Linux","archived":false,"fork":false,"pushed_at":"2025-08-19T08:39:34.000Z","size":1195,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-22T09:42:19.971Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eaceto.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-10T18:34:04.000Z","updated_at":"2025-08-19T08:33:28.000Z","dependencies_parsed_at":"2025-06-10T00:12:15.647Z","dependency_job_id":null,"html_url":"https://github.com/eaceto/OpenCoreLocation","commit_stats":null,"previous_names":["eaceto/opencorelocation"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/eaceto/OpenCoreLocation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eaceto%2FOpenCoreLocation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eaceto%2FOpenCoreLocation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eaceto%2FOpenCoreLocation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eaceto%2FOpenCoreLocation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eaceto","download_url":"https://codeload.github.com/eaceto/OpenCoreLocation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eaceto%2FOpenCoreLocation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34554511,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-19T02:00:06.005Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-11T09:59:00.380Z","updated_at":"2026-06-20T01:31:54.801Z","avatar_url":"https://github.com/eaceto.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenCoreLocation\n\n[![Swift](https://img.shields.io/badge/Swift-6.0+-orange.svg)](https://swift.org)\n[![Platforms](https://img.shields.io/badge/Platforms-Linux%20%7C%20macOS%20%7C%20iOS%20%7C%20tvOS%20%7C%20watchOS-blue.svg)](https://swift.org)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nOpenCoreLocation is a comprehensive Swift package that brings Apple's **CoreLocation** functionality to **Linux** while maintaining full API compatibility. This library enables seamless cross-platform development by providing the same CoreLocation APIs you know and love on Linux systems.\n\n## 🚀 Key Features\n\n### 📍 **Multi-Provider Location System**\n- **GPS Provider**: High-accuracy positioning via gpsd integration (1-10m accuracy)\n- **WiFi Provider**: Medium-accuracy positioning using WiFi access points (40m+ accuracy)  \n- **IP Provider**: Low-accuracy geolocation via IP address (1km+ accuracy)\n- **Intelligent Fallback**: Automatically selects best available provider based on desired accuracy\n\n### 🎯 **Advanced Location Management**\n- **Distance Filter**: Only report location updates when device moves beyond specified threshold\n- **Accuracy-Based Selection**: Automatic provider selection based on `CLLocationAccuracy` constants\n- **Thread-Safe Implementation**: Concurrent queue-based architecture for optimal performance\n- **Smart Caching**: Reduces redundant API calls and improves battery life\n\n### 🔍 **Region Monitoring \u0026 Geofencing**\n- **Circular Regions**: Monitor entry/exit events for geographic areas\n- **Software Geofencing**: Real-time boundary detection without hardware dependencies\n- **Selective Notifications**: Configure entry-only, exit-only, or both event types\n- **Multiple Region Support**: Monitor multiple regions simultaneously\n- **Background Monitoring**: Automatic region checking with location updates\n\n### 🔋 **Background Location Updates** *(New in v1.2.0)*\n- **Adaptive Intervals**: Dynamic update frequencies based on app state and movement\n  - Foreground: 1-second intervals for real-time tracking\n  - Background: 30-second intervals for efficiency\n  - Stationary: 60-second intervals when no movement detected\n- **Automatic Pausing**: Smart `pausesLocationUpdatesAutomatically` implementation\n  - Detects when device is stationary (\u003c 10m movement for 60s)\n  - Automatically resumes when movement is detected\n- **Power Efficiency**: Intelligent provider selection and caching for battery optimization\n- **Real-time Adaptation**: Seamless transitions between update modes\n\n### 🌍 **Comprehensive Geographic Utilities**\n- **CLLocationUtils**: Centralized geographic calculations and utilities\n- **Distance Calculations**: Accurate great-circle distance using haversine formula\n- **Bearing Calculations**: Compass direction between coordinate points\n- **Coordinate Validation**: Input validation for latitude/longitude ranges\n\n### 📮 **Geocoding Services**\n- **Forward Geocoding**: Address → Coordinates using OpenStreetMap\n- **Reverse Geocoding**: Coordinates → Address information\n- **Async/Await Support**: Modern Swift concurrency patterns\n\n## 🏗️ Project Status\n\nOpenCoreLocation is production-ready with comprehensive testing and documentation. The library provides a robust, feature-complete implementation of CoreLocation APIs for Linux systems.\n\n### 🆕 Recent Updates (v1.2.0)\n- **🆕 Background Location Updates**: Full implementation of `allowsBackgroundLocationUpdates` with adaptive intervals\n- **🆕 Automatic Pausing**: Smart `pausesLocationUpdatesAutomatically` with stationary detection\n- **🆕 Adaptive Intervals**: Dynamic update frequencies (1s foreground, 30s background, 60s stationary)\n- **🆕 Swift 6.0 Support**: Complete upgrade to Swift 6.0 with strict concurrency compliance\n- **🆕 Enhanced Examples**: New BackgroundLocationExample demonstrating power-efficient tracking\n- **✅ Cross-Platform Build**: Improved CI/CD and development workflow\n\n### 📜 Previous Updates (v1.1.0)\n- **✅ Real-time Region Monitoring**: Complete geofencing implementation with entry/exit callbacks\n- **✅ Enhanced Documentation**: Full API documentation with GitHub Pages deployment\n- **✅ Development Tools**: Makefile, automated testing, and CI/CD integration\n- **✅ Improved Testing**: 50+ test cases covering all major functionality\n- **✅ Geographic Utilities**: Centralized `CLLocationUtils` with distance/bearing calculations\n- **✅ Multi-provider Architecture**: Intelligent fallback system for GPS, WiFi, and IP providers\n\n### ✅ Implemented Features\n- [x] **Core Location APIs**: `CLLocationManager`, `CLLocationManagerDelegate`, `CLLocation`\n- [x] **Background Location Updates**: `allowsBackgroundLocationUpdates` with adaptive intervals\n- [x] **Automatic Pausing**: `pausesLocationUpdatesAutomatically` with stationary detection\n- [x] **Geocoding**: `CLGeocoder` with OpenStreetMap integration  \n- [x] **Region Monitoring**: `CLRegion`, `CLCircularRegion` with real-time geofencing\n- [x] **Multi-Provider System**: GPS, WiFi, and IP-based location providers\n- [x] **Distance Filtering**: Intelligent location update filtering\n- [x] **Geographic Utilities**: `CLLocationUtils` with distance/bearing calculations\n- [x] **Cross-Platform**: Support for Linux, macOS, iOS, tvOS, and watchOS\n- [x] **Swift 6.0 Compatibility**: Full concurrency compliance and modern Swift features\n- [x] **Comprehensive Testing**: 60+ test cases with \u003e90% code coverage\n- [x] **Region Geofencing**: Entry/exit detection with delegate callbacks\n- [x] **Documentation System**: Complete API documentation with Jazzy integration\n\n### 🚧 Future Enhancements\n- [ ] **Visit Detection**: `CLVisit` for detecting significant locations\n- [ ] **Beacon Ranging**: iBeacon support for proximity detection\n- [ ] **Advanced Background Modes**: System-level daemon integration for Linux\n- [ ] **Region Monitoring on GPS Loss**: Fallback strategies for provider failures\n\n## 📦 Installation\n\n### Swift Package Manager\n\nAdd OpenCoreLocation to your project using Swift Package Manager:\n\n```swift\n// swift-tools-version:6.0\nimport PackageDescription\n\nlet package = Package(\n    name: \"YourProject\",\n    platforms: [\n        .macOS(.v10_15), .iOS(.v13), .tvOS(.v13), .watchOS(.v6)\n    ],\n    dependencies: [\n        .package(url: \"https://github.com/eaceto/OpenCoreLocation.git\", from: \"1.2.0\")\n    ],\n    targets: [\n        .target(\n            name: \"YourProject\",\n            dependencies: [\"OpenCoreLocation\"]\n        )\n    ]\n)\n```\n\n### Xcode Integration\n1. Open your Xcode project\n2. Go to **File \u003e Add Package Dependencies**  \n3. Enter: `https://github.com/eaceto/OpenCoreLocation.git`\n4. Select the latest version\n\n## 🛠️ System Requirements\n\n### Linux GPS Support (Optional)\nFor high-accuracy GPS positioning on Linux:\n\n```bash\n# Install GPS daemon\nsudo apt-get update\nsudo apt-get install gpsd gpsd-clients\n\n# Start GPS service\nsudo systemctl start gpsd\nsudo systemctl enable gpsd\n```\n\n### WiFi Positioning (Optional)\nWiFi-based positioning uses NetworkManager (usually pre-installed):\n\n```bash\n# Ensure NetworkManager is available\nsudo apt-get install network-manager\n```\n\n\u003e **Note**: OpenCoreLocation works without GPS or WiFi by falling back to IP-based geolocation\n\n## 📖 Usage\n\n### Basic Location Tracking\n\n```swift\n#if os(Linux)\nimport OpenCoreLocation\n#else\nimport CoreLocation\n#endif\n\nclass LocationManagerDelegate: NSObject, CLLocationManagerDelegate {\n    func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]) {\n        guard let location = locations.last else { return }\n        print(\"📍 Location: \\(location.coordinate.latitude), \\(location.coordinate.longitude)\")\n        print(\"🎯 Accuracy: \\(location.horizontalAccuracy)m\")\n    }\n    \n    func locationManager(_ manager: CLLocationManager, didFailWithError error: Error) {\n        print(\"❌ Location error: \\(error.localizedDescription)\")\n    }\n}\n\n// Create and configure location manager\nlet locationManager = CLLocationManager()\nlet delegate = LocationManagerDelegate()\n\nlocationManager.delegate = delegate\nlocationManager.desiredAccuracy = kCLLocationAccuracyBest\nlocationManager.distanceFilter = 10.0  // Only update if moved \u003e10 meters\n\n// Request authorization and start updates\nlocationManager.requestWhenInUseAuthorization()\nlocationManager.startUpdatingLocation()\n```\n\n### Advanced Accuracy Control\n\n```swift\n// High-accuracy GPS tracking (1-5m accuracy)\nlocationManager.desiredAccuracy = kCLLocationAccuracyBest\n\n// Medium-accuracy WiFi positioning (20-100m accuracy)  \nlocationManager.desiredAccuracy = kCLLocationAccuracyHundredMeters\n\n// Low-accuracy IP geolocation (1-5km accuracy)\nlocationManager.desiredAccuracy = kCLLocationAccuracyKilometer\n\n// Disable distance filtering for all updates\nlocationManager.distanceFilter = kCLDistanceFilterNone\n```\n\n### Geocoding\n\n```swift\nimport OpenCoreLocation\n\nlet geocoder = CLGeocoder()\n\n// Forward geocoding (Address → Coordinates)\nlet placemarks = try await geocoder.geocodeAddressString(\"1 Apple Park Way, Cupertino, CA\")\nif let location = placemarks.first?.location {\n    print(\"📍 Apple Park: \\(location.coordinate)\")\n}\n\n// Reverse geocoding (Coordinates → Address)\nlet location = CLLocation(latitude: 37.3317, longitude: -122.0302)\nlet reverseResults = try await geocoder.reverseGeocodeLocation(location)\nif let placemark = reverseResults.first {\n    print(\"📮 Address: \\(placemark.name ?? \"Unknown\")\")\n}\n```\n\n### Geographic Utilities\n\n```swift\nimport OpenCoreLocation\n\n// Distance calculations\nlet sanFrancisco = CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194)\nlet newYork = CLLocationCoordinate2D(latitude: 40.7128, longitude: -74.0060)\n\nlet distance = CLLocationUtils.calculateDistance(from: sanFrancisco, to: newYork)\nprint(\"🌍 SF to NYC: \\(distance/1000) km\")\n\n// Using extensions\nlet distanceExt = sanFrancisco.distance(to: newYork)\nlet bearing = sanFrancisco.bearing(to: newYork)\nprint(\"🧭 Bearing: \\(bearing)° (roughly East)\")\n\n// Coordinate validation\nlet isValid = CLLocationUtils.isValidCoordinate(latitude: 37.7749, longitude: -122.4194)\nprint(\"✅ Valid coordinates: \\(isValid)\")\n```\n\n### Region Monitoring \u0026 Geofencing\n\n#### Basic Region Setup\n```swift\n// Create circular region for monitoring\nlet center = CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194) // San Francisco\nlet region = CLCircularRegion(center: center, radius: 500.0, identifier: \"downtown-sf\")\n\n// Configure notifications\nregion.notifyOnEntry = true   // Get notified when entering region\nregion.notifyOnExit = true    // Get notified when exiting region\n\n// Test coordinate containment\nlet testPoint = CLLocationCoordinate2D(latitude: 37.7750, longitude: -122.4195)\nlet isInside = region.contains(testPoint)\nprint(\"📍 Point inside region: \\(isInside)\")\n```\n\n#### Real-time Geofencing\n```swift\nextension LocationManagerDelegate {\n    func locationManager(_ manager: CLLocationManager, didEnterRegion region: CLRegion) {\n        print(\"🎯 Entered region: \\(region.identifier)\")\n        // Trigger entry actions (notifications, data sync, etc.)\n    }\n    \n    func locationManager(_ manager: CLLocationManager, didExitRegion region: CLRegion) {\n        print(\"🚪 Exited region: \\(region.identifier)\")  \n        // Trigger exit actions (cleanup, notifications, etc.)\n    }\n    \n    func locationManager(_ manager: CLLocationManager, didDetermineState state: CLRegionState, for region: CLRegion) {\n        switch state {\n        case .inside:\n            print(\"📍 Currently inside: \\(region.identifier)\")\n        case .outside:\n            print(\"🌍 Currently outside: \\(region.identifier)\")\n        case .unknown:\n            print(\"❓ Region state unknown: \\(region.identifier)\")\n        }\n    }\n    \n    func locationManager(_ manager: CLLocationManager, didStartMonitoringFor region: CLRegion) {\n        print(\"👀 Started monitoring: \\(region.identifier)\")\n        // Request initial state\n        manager.requestState(for: region)\n    }\n}\n\n// Start monitoring regions\nlocationManager.startMonitoring(for: region)\n\n// Query current region state\nlocationManager.requestState(for: region)\n\n// Stop monitoring when done\nlocationManager.stopMonitoring(for: region)\n```\n\n#### Multiple Region Management\n```swift\n// Monitor multiple regions simultaneously\nlet regions = [\n    CLCircularRegion(center: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194), \n                    radius: 500.0, identifier: \"downtown-sf\"),\n    CLCircularRegion(center: CLLocationCoordinate2D(latitude: 37.7849, longitude: -122.4094), \n                    radius: 200.0, identifier: \"office\"),\n    CLCircularRegion(center: CLLocationCoordinate2D(latitude: 37.7649, longitude: -122.4394), \n                    radius: 100.0, identifier: \"home\")\n]\n\nregions.forEach { region in\n    region.notifyOnEntry = true\n    region.notifyOnExit = true\n    locationManager.startMonitoring(for: region)\n}\n\nprint(\"📍 Monitoring \\(locationManager.monitoredRegions.count) regions\")\n```\n\n## 📊 Accuracy Comparison\n\n| Provider | Accuracy | Update Interval | Use Case | Linux Requirements |\n|----------|----------|----------------|----------|-------------------|\n| **GPS** | 1-10m | 1 second | Navigation, fitness tracking, precise geofencing | gpsd + GPS hardware |\n| **WiFi** | 20-100m | 30 seconds | General location services, urban geofencing | WiFi networks |\n| **IP** | 500m-5km | 30 seconds | Regional services, weather, city-level geofencing | Internet connection |\n\n### Geofencing Capabilities\n- **Region Radius**: 10m - 100km (software-configurable)\n- **Entry/Exit Detection**: Real-time boundary crossing detection\n- **Multiple Regions**: Monitor up to 20 regions simultaneously  \n- **Background Monitoring**: Automatic checking with location updates\n- **Accuracy**: Depends on underlying location provider (GPS: ±5m, WiFi: ±50m, IP: ±1km)\n\n## 📚 Documentation \u0026 Examples\n\n### API Documentation\n**Online Documentation**: [https://eaceto.github.io/OpenCoreLocation](https://eaceto.github.io/OpenCoreLocation)\n\n### Example Projects\nThe `/Examples` directory contains demonstration code for all major features:\n\n- **`LocationAccuracyExample.swift`**: Multi-provider accuracy system demonstration\n- **`DistanceFilterDemo.swift`**: Distance filtering and battery optimization examples  \n- **`LocationUtilsDemo.swift`**: Geographic utilities and calculations showcase\n- **`RegionMonitoringExample.swift`**: Complete geofencing implementation with entry/exit detection\n\n#### Running Examples\n```bash\n# Run examples using Swift Package Manager\nswift run LocationAccuracyExample     # Multi-provider accuracy testing\nswift run DistanceFilterDemo          # Distance filtering demonstration  \nswift run LocationUtilsDemo           # Geographic utilities showcase\nswift run RegionMonitoringExample     # Interactive region monitoring demo\n```\n\n## 🔄 Cross-Platform Usage\n\nOpenCoreLocation maintains full API compatibility with Apple's CoreLocation:\n\n```swift\n// Same code works on all platforms\n#if os(Linux)\nimport OpenCoreLocation\n#else\nimport CoreLocation\n#endif\n\n// Identical API usage across platforms\nlet manager = CLLocationManager()\nmanager.desiredAccuracy = kCLLocationAccuracyBest\nmanager.startUpdatingLocation()\n```\n\n## 🤝 Contributing\n\nContributions are welcome! For development setup, testing, and contribution guidelines, see:\n\n**👨‍💻 [Developer Documentation](README-DEVS.md)** - Complete guide for contributors and maintainers\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Inspired by Apple's CoreLocation framework\n- Uses OpenStreetMap for geocoding services\n- Built with Swift's modern concurrency features\n\n---\n\n**Developed by [Ezequiel (Kimi) Aceto](https://eaceto.dev)**\n\n*Making CoreLocation truly cross-platform* 🌍","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feaceto%2Fopencorelocation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feaceto%2Fopencorelocation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feaceto%2Fopencorelocation/lists"}