{"id":15032505,"url":"https://github.com/malcommac/swiftlocation","last_synced_at":"2025-05-14T09:11:59.779Z","repository":{"id":43367292,"uuid":"39890718","full_name":"malcommac/SwiftLocation","owner":"malcommac","description":"⚓️ Async/Await CLLocationManager Wrapper for Apple Platforms","archived":false,"fork":false,"pushed_at":"2024-04-24T15:59:46.000Z","size":8112,"stargazers_count":3418,"open_issues_count":9,"forks_count":431,"subscribers_count":89,"default_branch":"master","last_synced_at":"2025-04-03T16:07:52.008Z","etag":null,"topics":["cllocationmanager","location-services","locationtracking","swift","swift-library","swiftlang"],"latest_commit_sha":null,"homepage":"","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/malcommac.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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},"funding":{"github":["malcommac"]}},"created_at":"2015-07-29T11:51:30.000Z","updated_at":"2025-04-03T08:47:37.000Z","dependencies_parsed_at":"2022-07-08T06:00:24.257Z","dependency_job_id":"279363a9-8b2f-4a02-97e3-65ea78a7b11e","html_url":"https://github.com/malcommac/SwiftLocation","commit_stats":{"total_commits":423,"total_committers":38,"mean_commits":"11.131578947368421","dds":0.2293144208037825,"last_synced_commit":"f8ec8e97095eb3a5312370ad94b921768217625f"},"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/malcommac%2FSwiftLocation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/malcommac%2FSwiftLocation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/malcommac%2FSwiftLocation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/malcommac%2FSwiftLocation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/malcommac","download_url":"https://codeload.github.com/malcommac/SwiftLocation/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248335083,"owners_count":21086508,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["cllocationmanager","location-services","locationtracking","swift","swift-library","swiftlang"],"created_at":"2024-09-24T20:18:35.309Z","updated_at":"2025-04-11T03:28:12.887Z","avatar_url":"https://github.com/malcommac.png","language":"Swift","readme":"\u003cp align=\"center\"\u003e\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"./assets/swiftlocation-dark.png\" width=\"350\"\u003e\n  \u003cimg alt=\"logo-library\" src=\"./assets/swiftlocation-light.png\" width=\"350\"\u003e\n\u003c/picture\u003e\n\u003c/p\u003e\n\n[![Platform](https://img.shields.io/badge/Platforms-iOS%20%7C%20macOS%20%7C%20watchOS%20%7C%20tvOS%20-4E4E4E.svg?colorA=28a745)](#installation)\n[![Swift](https://img.shields.io/badge/Swift-5.3_5.4_5.5_5.6-orange?style=flat-square)](https://img.shields.io/badge/Swift-5.5_5.6_5.7_5.8_5.9-Orange?style=flat-square)\n[![Swift Package Manager](https://img.shields.io/badge/Swift_Package_Manager-compatible-orange?style=flat-square)](https://img.shields.io/badge/Swift_Package_Manager-compatible-orange?style=flat-square)\n\n**SwiftLocation is a lightweight wrapper around Apple's CoreLocation framework that supports the new Swift Concurrency model.**  \n\n*This means **no more delegate pattern to deal with, nor completion blocks**.  \nYou can manage location requests, region, and beacon monitoring directly using the new async/await syntax.*\n\nWould you, for example, get the current user location?  \n*It's just 2 lines code away:*\n\n```swift\ntry await location.requestPermission(.whenInUse) // obtain the permissions\nlet userLocation = try await location.requestLocation() // get the location\n```\n\n# How it works\n\nSwiftLocation is quite straightforward to use.  \nSimply create your own `Location` instance and use one of the available methods.\n\n\u003e [!IMPORTANT]  \n\u003e Some APIs may not available under some of the supported platforms due to specific hardware constraints.\n\n- [How it works](#how-it-works)\n  - [What's new in 6.0](#whats-new-in-60)\n  - [Service Location Status](#service-location-status)\n  - [Authorization Status](#authorization-status)\n  - [Accuracy Authorization Level](#accuracy-authorization-level)\n  - [Request Location Permission](#request-location-permission)\n    - [Provide descriptions of how you use location services](#provide-descriptions-of-how-you-use-location-services)\n  - [Request Temporary Precision Permission](#request-temporary-precision-permission)\n  - [Continous Location Monitoring](#continous-location-monitoring)\n  - [Request One-Shot User Location](#request-one-shot-user-location)\n  - [Visits Monitoring](#visits-monitoring)\n  - [Significant Location Changes Monitoring](#significant-location-changes-monitoring)\n  - [Device Heading Monitoring](#device-heading-monitoring)\n  - [Beacon Ranging](#beacon-ranging)\n- [Testing Suite \\\u0026  Mocked CLLocationManager](#testing-suite---mocked-cllocationmanager)\n- [Installation via SPM](#installation-via-spm)\n- [Support This Work ❤️](#support-this-work-️)\n- [License](#license)\n- [Contributing](#contributing)\n\n## What's new in 6.0\n\nThe new 6.0 milestone is a completely rewritten version designed to support async/await optimally. We are also focused on supporting all CoreLocation features without creating an overwhelmed package.  \nAll the features are supported by a complete unit tests suite.\n\nThis new version is also distributed only via Swift Package Manager (5.5+) and it's compatible with all the Apple Platforms: iOS 14+, macOS 11+, watchOS 7+, tvOS 14+.\n\n*The features from version 5.x - geocoding, ip resolve, autocomplete - will be included as separate downloadable modules later in the development process.*\n\n## Service Location Status\n\nUse the `location.locationServicesEnabled` to get the current status of the location services.  \nIn order to monitor changes you can use the `AsyncStream`'s startMonitoringLocationServices()` method:\n\n```swift\nfor await event in await location.startMonitoringLocationServices() {\n print(\"Location Services are \\(event.isLocationEnabled ? \"enabled\" : \"disabled\")\"\n // break to interrupt the stream\n}\n```\n\nYou can stop the stream at any moment using `break`; it will call the `stopMonitoringLocationServices()` automatically on used `Location`` instance.\n\n## Authorization Status\n\nYou can obtain the current status of the authorization status by using the `location.authorizationStatus` property.  \nIf you need to monitor changes to this value you can use the `AsyncStream` offered by `startMonitoringAuthorization()` method:\n\n```swift\nfor await event in await location.startMonitoringAuthorization() {\n  print(\"Authorization status did change: \\(event.authorizationStatus)\")\n  // break to interrupt the stream\n}\n```\n\n## Accuracy Authorization Level\n\nThe `location.accuracyAuthorization` offers a one shot value of the current precision level offered by your application.  \nWhen you need to monitor changes you can use the `AsyncStream` offered by `startMonitoringAccuracyAuthorization()`:\n\n```swift\nfor await event in await location.startMonitoringAccuracyAuthorization() {\n  print(\"Accuracy authorization did change: \\(event.accuracyAuthorization.description)\")\n  // break to interrupt the stream\n}\n```\n\n## Request Location Permission\n\nAlso the request location permission is managed via async await. You can use the `requestPermission()` method once you have properly configured your `Info.plist` file:\n\n```swift\n// return obtained CLAuthorizationStatus level\nlet obtaninedStatus = try await location.requestPermission(.whenInUse)\n```\n\n### Provide descriptions of how you use location services\n\nThe first time you make an authorization request, the system displays an alert asking the person to grant or deny the request. The alert includes a usage description string that explains why you want access to location data.  \n\nYou provide this string in your app’s Info.plist file and use it to inform people about how your app uses location data.\n\nCore Location supports different usage strings for each access level. You must include a usage description string for When in Use access. If your app supports Always access, provide an additional string explaining why you want the elevated privileges. The following table lists the keys to include in your Info.plist and when to include them.\n\n| Usage key                                                 | Required when:                                                                   |\n|-----------------------------------------------------------|----------------------------------------------------------------------------------|\n| `NSLocationWhenInUseUsageDescription`              | The app requests When in Use or Always authorization.                            |\n| `NSLocationAlwaysAndWhenInUseUsageDescription` | The app requests Always authorization.                                           |\n| `NSLocationTemporaryUsageDescriptionDictionary`             | Used when you want to temporary extend the precision of your authorization level |\n|                                                           |                                                                                  |\n\n## Request Temporary Precision Permission\n\nIf the App does not require an exact location for all of its features, but it is required to have accurate one only for specific features (i.e during checkout, booking service, etc) — then App may ask for temporary accuracy level for that session only using the `requestTemporaryPrecisionAuthorization(purpose:)` method:\n\n```swift\n// return CLAccuracyAuthorization value\nlet status = try await location.requestTemporaryPrecisionAuthorization(purpose: \"booking\")\n```\n\n## Continous Location Monitoring\n\nIf you need to continous monitoring new locations from user's device you can use the `AsyncStream` offered by `startMonitoringLocations()`:\n\n```swift\nfor await event in try await location.startMonitoringLocations() {\n    switch event {\n    case .didPaused:\n\t// location updates paused\n    case .didResume:\n    // location updates resumed\n    case let .didUpdateLocations(locations):\n    // new locations received   \n    case let .didFailed(error):\n    // an error has occurred   \n    }\n    // break to stop the stream\n}\n```\n\n## Request One-Shot User Location\n\nSometimes you may need to get the user location as single value. The async's `requestLocation(accuracy:timeout:)` method was created to return an optionally filtered location within a valid time interval:\n\n```swift\n// Simple implementation to get the last user location\nlet location = try await location.requestLocation()\n\n// Optionally you can return a value only if satisfy one or more constraints\nlet location = try await location.requestLocation(accuracy: [\n    .horizontal(100) // has an horizontal accuracy of 100 meters or lower\n], timeout: 8) // wait for response for a max of 8 seconds\n```\n\nFilters include horizontal/vertical, speed, course accuracy and it offer the opportunity to set a custom filter functions as callback.\n\n## Visits Monitoring\n\nVisits monitoring allows you to observe places that the user has been.  \nVisit objects are created by the system and delivered by the CLLocationManager. \nThe visit includes the location where the visit occurred and information about the arrival and departure times as relevant.\n\nTo monitor visits you can use the `AsyncStream`'s `startMonitoringVisits()` method:\n\n```swift\nfor await event in await location.startMonitoringVisits() {\n    switch event {\n    case let .didVisit(place):\n    // a new CLVisit object has been received.   \n    case let .didFailWithError(error):\n    // an error has occurred\n    }\n}\n```\n\n## Significant Location Changes Monitoring\n\nThe `AsyncStream`'s `startMonitoringSignificantLocationChanges()` method starts the generation of updates based on significant location changes.\n\n```swift\nfor await event in await self.location.startMonitoringSignificantLocationChanges() {\n    switch event {\n    case .didPaused:\n    // stream paused\n    case .didResume:\n    // stream resumed\n    case .didUpdateLocations(locations):\n    // new locations received\n    case let .didFailWithError(error):\n    // an error has occured\n    }\n\t// break to stop the stream\n}\n```\n\n## Device Heading Monitoring\n\nTo get updates about the current device's heading use the `AsyncStream` offered by `startUpdatingHeading()` method:\n\n```swift\nfor await event in await self.location.startUpdatingHeading() {\n\t// a new heading value has been generated\n}\n```\n\n## Beacon Ranging\n\nBeacon ranging is offered by the `AsyncStream`'s `startRangingBeacons()` method:\n\n```swift\nlet constraint: CLBeaconIdentityConstraint = ...\nfor await event in await location.startRangingBeacons(satisfying: constraint) {\n\t// a new event has been generated\n}\n```\n\n# Testing Suite \u0026  Mocked CLLocationManager\n\nSwiftLocation is distribuited with an extensive unit testing suite you can found into the `SwiftLocationTests` folder.  \nInside the suite you will also found the `MockedLocationManager.swift` file which is a `CLLocationManager` mock class you can use to provide the testing suite for your application. By configuring and extending this file you will be able to mock results of location requests and monitoring directly in your host app.\n\n\n# Installation via SPM\n\nSwiftLocation is offered via Swift Package Manager.  \nAdd it as a dependency in a Swift Package, and add it to your `Package.swift`:\n\n```swift\ndependencies: [\n  .package(url: \"https://github.com/malcommac/SwiftLocation.git\", from: \"6.0.0\")\n]\n```\n# Support This Work ❤️\n\nIf you love this library and wanna encourage further development **consider becoming a sponsor of my work** via [Github Sponsorship](https://github.com/sponsors/malcommac).  \n\n# License\n\nThis package was created and maintaned by [Daniele Margutti](https://github.com/malcommac).  \n\n- [LinkedIn Profile](https://www.linkedin.com/in/danielemargutti/)\n- [X/Twitter](http://twitter.com/danielemargutti)\n- [Website](https://www.danielemargutti.com)\n\nIt was distribuited using [MIT License](https://github.com/malcommac/SwiftLocation/blob/master/LICENSE.md).\n\n# Contributing\n\n- If you need help or you'd like to ask a general question, open an issue.\n- If you found a bug, open an issue.\n- If you have a feature request, open an issue.\n- If you want to contribute, submit a pull request.\n\nRead the [CONTRIBUTING](CONTRIBUTING.md) file for more informations.\n","funding_links":["https://github.com/sponsors/malcommac"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmalcommac%2Fswiftlocation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmalcommac%2Fswiftlocation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmalcommac%2Fswiftlocation/lists"}