{"id":21730137,"url":"https://github.com/nventive/geolocatorservice","last_synced_at":"2025-03-20T23:22:27.165Z","repository":{"id":45304542,"uuid":"290855589","full_name":"nventive/GeolocatorService","owner":"nventive","description":"A multi-platform abstraction built on top of Geolocator from Windows.Devices.Geolocation.","archived":false,"fork":false,"pushed_at":"2025-03-14T18:10:11.000Z","size":937,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":26,"default_branch":"main","last_synced_at":"2025-03-17T11:55:10.487Z","etag":null,"topics":["android","dotnet","geolocation","ios","mobile","uno-platform","uwp"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nventive.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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}},"created_at":"2020-08-27T18:46:22.000Z","updated_at":"2025-03-14T18:10:14.000Z","dependencies_parsed_at":"2024-06-21T14:08:27.452Z","dependency_job_id":"71deee73-4a65-415a-96f1-667c54c34bab","html_url":"https://github.com/nventive/GeolocatorService","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":"nventive/Template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nventive%2FGeolocatorService","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nventive%2FGeolocatorService/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nventive%2FGeolocatorService/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nventive%2FGeolocatorService/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nventive","download_url":"https://codeload.github.com/nventive/GeolocatorService/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244031017,"owners_count":20386534,"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":["android","dotnet","geolocation","ios","mobile","uno-platform","uwp"],"created_at":"2024-11-26T04:12:31.483Z","updated_at":"2025-03-20T23:22:27.157Z","avatar_url":"https://github.com/nventive.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GeolocatorService\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square)](LICENSE) ![Version](https://img.shields.io/nuget/v/GeolocatorService?style=flat-square) ![Downloads](https://img.shields.io/nuget/dt/GeolocatorService?style=flat-square)\n\nA service to get the user's current location, based on Geolocator, suited to WinUI, UWP or [Uno](https://platform.uno/) apps.\n\nGeolocatorService aims to simplify getting the user's current location and handling most common scenarios, including getting the permission to obtain this location and handling cases where this permission is denied.\n\n## Getting Started\n\n1. ### Add Package\n\n   #### .Net Mobile / WinUI\n   \n   Add the GeolocatorService.Uno.WinUI nuget package to your project heads.\n      \n   #### Xamarin / UWP\n   Add the GeolocatorService nuget package to your project heads.\n   \n   ### Reactive Extensions\n   To have access to reactive extensions such as `GetAndObserveLocation`, add the `GeolocatorService.Reactive` nuget package to your project.\n\n1. ### Add the relevant permissions\n\n   #### Windows\n   \n   Add the Location capability in your manifest.\n\n   ``` xml\n    \u003c!-- Package.appxmanifest --\u003e\n    \u003cPackage ...\u003e\n        \u003c!-- (...) --\u003e\n        \u003cCapabilities\u003e\n            \u003cDeviceCapability Name=\"location\"/\u003e\n        \u003c/Capabilities\u003e\n    \u003c/Package\u003e\n   ```\n    \u003cdetails\u003e\n        \u003csummary\u003eVisual Studio appxmanisfest UI\u003c/summary\u003e\n\n    ![appxmanifest](./doc/img/appxmanisfest.png)\n    \u003c/details\u003e\n   \n   #### iOS\n   \n   Include the `NSLocationWhenInUsageDescription` and `NSLocationUsageDescription` entries in your info.plist file. These values define the message shown to users when they are asked for location permission. For instance,\n   \n   ``` xml\n    \u003c!-- info.plist --\u003e\n    \u003ckey\u003eNSLocationWhenInUseUsageDescription\u003c/key\u003e\n    \u003cstring\u003eTODO NSLocationWhenInUsageDescription\u003c/string\u003e\n    \u003ckey\u003eNSLocationUsageDescription\u003c/key\u003e\n    \u003cstring\u003eTODO NSLocationUsageDescription\u003c/string\u003e\n   ```\n   \n   #### Android\n   \n   Add the location permission to your AssemblyInfo.cs file.\n   \n   ``` cs\n    // AssemblyInfo.cs\n    [assembly: UsesPermission(Android.Manifest.Permission.AccessFineLocation)]\n   ```\n\n1. ### Instantiate GeolocatorService\n\n   Add GeoLocatorService :\n\n   ``` csharp\n   var locationService = new GeoLocatorService();\n   ```\n\n1. ### Request permission\n\n   After you have added the relevant location permission info to your project configuration, locate the spot in your code where you want to ask the user for their location permission. This [iOS guidelines](https://developer.apple.com/design/human-interface-guidelines/ios/app-architecture/requesting-permission/) or this [Android guidelines](https://developer.android.com/training/permissions/requesting) may help you decide. This must be done before accessing their location. Add the following line to do so:\n   \n   ``` cs\n   var isGranted = await locationService.RequestPermission(CancellationToken.None);\n   ```\n\n1. ### Request User location\n\n   If permission is granted, you are able to invoke the `GetLocation` function to obtain the user's current location.\n\n   ```csharp\n   Geocoordinate location = await locationService.GetLocation(CancellationToken.None);\n   ```\n\n## Features\n\n### Request Permission\n\n``` cs\n   var isGranted = await locationService.RequestPermission(CancellationToken.None);\n```\n\nYou may safely request the permission multiple times; the user will only get prompted as often as is necessary.\n\nFor instance, if you ask the user for their permission once and they decline, calling `RequestPermission` again will not prompt the user again, but simply return `false`.\n\nIf the user answers \"Allow once\", then calling `RequestPermission` again during the lifetime of the app will simply return `true`. Once the app is restarted, calling `RequestPermission` will prompt them for the permission once again, since their original permission has now expired.\n\nOnce permission is requested, you can use the various methods and extension methods of IGeolocatorService.\n\n### Request the user's location\n\nOnce you have obtained the location permission, it's a simple matter to obtain the location:\n\n``` cs\nif (isGranted)\n{\n    location = await locationService.GetLocation(CancellationToken.None);\n}\n//or\nvar locationOrDefault = await locationService.GetLocationOrDefault(CancellationToken.None);\n```\n\nWhen using `GetLocation`, if the user has not granted the location permission, an `InvalidOperationException` is thrown; therefore, we recommend not calling this method if you know the user has denied the location permission and this is a normal scenario. \n\nIn cases you are not sure of the permission status, we suggest employing the extension method named `GetLocationOrDefault` instead. This method will return null instead of throwing an exception, in case the permission was denied.\n\n### React to changes in the user's location or their permissions\n\n`IGeolocatorService` offers events to allow you to react when the user's location has changed, or when they have granted or denied permissions. Even if these changes occur while the app is in background, they will be raised when the app comes back to the foreground.\n\n``` cs\nlocationService.LocationChanged += OnLocationChanged;\nlocationService.LocationPermissionChanged += OnLocationPermissionChanged;\n```\n\n### Track the location and permission using Reactive Extensions\n\nGeolocatorService.Reactive adds a few extension methods which will allow your app to fluidly keep track of the user's location and permission status.\n\nFor instance, let's say your app wants to display relevant information to the user's location when it's available, and a completely different type of information when that location is unavailable (because the permission was denied or the device is unable to provide a location).\n\n``` cs\nIObservable\u003cPageContent\u003e content = locationService.GetAndObserveLocationOrDefault(ct)\n    .Select(location =\u003e\n    {\n        if (location == null)\n        {\n            // TODO Gets information which is independent of the location\n        }\n        else\n        {\n            // TODO Gets information pertinent to the location\n        }\n    });\n```\n\n### Geocoordinate\n\nPlease note that the value generated from a user's location depends on the capabilities of the platform. Not all devices can provide information such as `Altitude`, `Heading` (direction), and `Speed`.\n\nGeocoordinates offer details about the `Accuracy` of the data. Additionally, you can access the source of the data through `PositionSource`. This information can help you evaluate the precision of the collected data.\n\n## Breaking Changes\n\nPlease consult the [BREAKING CHANGES](BREAKING_CHANGES.md) for more information about breaking changes\nhistory.\n\n## Changelog\n\nPlease consult the [CHANGELOG](CHANGELOG.md) for more information about version\nhistory.\n\n## License\n\nThis project is licensed under the Apache 2.0 license - see the\n[LICENSE](LICENSE) file for details.\n\n## Contributing\n\nPlease read [CONTRIBUTING.md](CONTRIBUTING.md) for details on the process for\ncontributing to this project.\n\nBe mindful of our [Code of Conduct](CODE_OF_CONDUCT.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnventive%2Fgeolocatorservice","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnventive%2Fgeolocatorservice","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnventive%2Fgeolocatorservice/lists"}