{"id":13989392,"url":"https://github.com/yayaa/LocationManager","last_synced_at":"2025-07-22T10:32:18.140Z","repository":{"id":3960594,"uuid":"51519587","full_name":"yayaa/LocationManager","owner":"yayaa","description":"Simplify getting user's location for Android","archived":false,"fork":false,"pushed_at":"2023-09-04T12:53:53.000Z","size":414,"stargazers_count":807,"open_issues_count":7,"forks_count":186,"subscribers_count":31,"default_branch":"master","last_synced_at":"2024-08-09T13:15:48.541Z","etag":null,"topics":["android","google-play-services","gps","location-picker","location-services","locationmanager","network"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yayaa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2016-02-11T14:22:59.000Z","updated_at":"2024-07-28T16:25:14.000Z","dependencies_parsed_at":"2022-07-14T04:50:30.754Z","dependency_job_id":"d248e6ef-b3a2-467f-af27-5a767c3bcd35","html_url":"https://github.com/yayaa/LocationManager","commit_stats":{"total_commits":130,"total_committers":11,"mean_commits":"11.818181818181818","dds":"0.46923076923076923","last_synced_commit":"e4897fd68fb8d6f0f218573550c811e76b98efae"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yayaa%2FLocationManager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yayaa%2FLocationManager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yayaa%2FLocationManager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yayaa%2FLocationManager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yayaa","download_url":"https://codeload.github.com/yayaa/LocationManager/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227079286,"owners_count":17727990,"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","google-play-services","gps","location-picker","location-services","locationmanager","network"],"created_at":"2024-08-09T13:01:37.908Z","updated_at":"2024-11-29T08:31:10.702Z","avatar_url":"https://github.com/yayaa.png","language":"Java","funding_links":[],"categories":["Java"],"sub_categories":[],"readme":"# LocationManager\n\n\u003ca href=\"http://developer.android.com/index.html\" target=\"_blank\"\u003e\u003cimg src=\"https://img.shields.io/badge/platform-android-green.svg\"/\u003e\u003c/a\u003e \u003ca href=\"https://android-arsenal.com/api?level=14\" target=\"_blank\"\u003e\u003cimg src=\"https://img.shields.io/badge/API-14%2B-green.svg?style=flat\"/\u003e\u003c/a\u003e [![codecov](https://codecov.io/gh/yayaa/LocationManager/branch/master/graph/badge.svg)](https://codecov.io/gh/yayaa/LocationManager) \u003ca href=\"http://www.methodscount.com/?lib=com.yayandroid%3ALocationManager%3A2.0.0\"\u003e\u003cimg src=\"https://img.shields.io/badge/Methods count-517-e91e63.svg\" target=\"_blank\"/\u003e\u003c/a\u003e \u003ca href=\"http://www.methodscount.com/?lib=com.yayandroid%3ALocationManager%3A2.0.0\"\u003e\u003cimg src=\"https://img.shields.io/badge/Size-70 KB-e91e63.svg\" target=\"_blank\"/\u003e\u003c/a\u003e\n\n\u003ca href=\"https://opensource.org/licenses/Apache-2.0\" target=\"_blank\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-Apache_v2.0-blue.svg?style=flat\"/\u003e\u003c/a\u003e \u003ca href=\"http://search.maven.org/#search%7Cga%7C1%7CLocationManager\" target=\"_blank\"\u003e\u003cimg src=\"https://img.shields.io/maven-central/v/com.yayandroid/LocationManager.svg\"/\u003e\u003c/a\u003e \u003ca href=\"http://android-arsenal.com/details/1/3148\" target=\"_blank\"\u003e\u003cimg src=\"https://img.shields.io/badge/Android%20Arsenal-LocationManager-brightgreen.svg?style=flat\"/\u003e\u003c/a\u003e\n\nTo get location on Android Devices, there are 'some' steps you need to go through!\nWhat are those? Let's see...\n\n\u003cul\u003e\n\u003cli\u003eCheck whether the application has required permission or not\u003c/li\u003e\n\u003cli\u003eIf not, ask runtime permissions from user\u003c/li\u003e\n\u003cli\u003eCheck whether user granted the permissions or not\u003c/li\u003e\n\u003c/ul\u003e\n\nLet's assume we got the permission, now what?\nWe have this cool Google Play Services optimised location provider [FusedLocationProviderClient][1] which provides a common location pool that any application use this api can retrieve location in which interval they require. It reduces battery usage, and decreases waiting time (most of the time) for location.\nYES, we want that! Right?\n\n\u003cul\u003e\n\u003cli\u003eCheck whether Google Play Services is available on device\u003c/li\u003e\n\u003cli\u003eIf not, see if user can handle this problem?\u003c/li\u003e\n\u003cli\u003eIf so, ask user to do it\u003c/li\u003e\n\u003cli\u003eThen, check again to see if user actually did it or not\u003c/li\u003e\n\u003cli\u003eIf user did actually handle it, then start location update request\u003c/li\u003e\n\u003cli\u003eOf course, handle GoogleApiClient connection issues first\u003c/li\u003e\n\u003cli\u003eAnd have a fallback plan, if you're not able to get location in certain time period\u003c/li\u003e\n\u003c/ul\u003e\n\nOuu and yes, this new even cooler SettingsApi, that user doesn't need to go to settings to activate GPS or Wifi. Isn't that cool, let's implement that too!\n\n\u003cul\u003e\n\u003cli\u003eCall SettingsApi to adapt device settings up to your location requirement\u003c/li\u003e\n\u003cli\u003eWait for the result and check your options\u003c/li\u003e\n\u003cli\u003eIs current settings are enough to get required location?\u003c/li\u003e\n\u003cli\u003eOr can you ask user to adapt them?\u003c/li\u003e\n\u003cli\u003eMaybe it is not even possible to use it.\u003c/li\u003e\n\u003cli\u003eLet's assume we asked user to adapt, but he/she didn't want to do it.\u003c/li\u003e\n\u003c/ul\u003e\n\nWell whatever we tried to optimise, right? But till now, all depends on GooglePlayServices what happens if user's device doesn't have GooglePlayServices, or user didn't want to handle GooglePlayServices issue or user did everything and waited long enough but somehow GooglePlayServices weren't able to return any location. What now?\nSurely we still have good old times GPS and Network Providers, right? Let's switch to them and see what we need to do!\n\n\u003cul\u003e\n\u003cli\u003eCheck whether GPS Provider is enabled or not\u003c/li\u003e\n\u003cli\u003eIf it is not, ask user to enable it\u003c/li\u003e\n\u003cli\u003eCheck again whether user actually did enable it or not\u003c/li\u003e\n\u003cli\u003eIf it is enabled, start location update request\u003c/li\u003e\n\u003cli\u003eBut switch to network if GPS is not retrieving location after waiting long enough\u003c/li\u003e\n\u003cli\u003eCheck whether Network Provider is enabled or not\u003c/li\u003e\n\u003cli\u003eIf it is, start location update request\u003c/li\u003e\n\u003cli\u003eIf none of these work, then fail\u003c/li\u003e\n\u003c/ul\u003e\n\nAll of these steps, just to retrieve user's current location. And in every application, you need to reconsider what you did and what you need to add for this time.\n\n\u003cb\u003eWith this library you just need to provide a Configuration object with your requirements, and you will receive a location or a fail reason with all the stuff are described above handled.\u003c/b\u003e\n \nThis library requires quite a lot of lifecycle information to handle all the steps between onCreate - onResume - onPause - onDestroy - onActivityResult - onRequestPermissionsResult.\nYou can simply use one of [LocationBaseActivity][2], [LocationBaseFragment][3], [LocationBaseService][4] or you can manually call those methods as required.\n\n[See the sample application][5] for detailed usage!\n\n## Configuration\n\nAll those settings below are optional. Use only those you really want to customize. Please do not copy-paste this configuration directly. If you want to use pre-defined configurations, see [Configurations][6].\n\n```java \nLocationConfiguration awesomeConfiguration = new LocationConfiguration.Builder()\n    .keepTracking(false)\n    .askForPermission(new PermissionConfiguration.Builder()\n        .permissionProvider(new YourCustomPermissionProvider())\n        .rationaleMessage(\"Gimme the permission!\")\n        .rationaleDialogProvider(new YourCustomDialogProvider())\n        .requiredPermissions(new String[] { permission.ACCESS_FINE_LOCATION })\n        .build())\n    .useGooglePlayServices(new GooglePlayServicesConfiguration.Builder()\n        .locationRequest(YOUR_CUSTOM_LOCATION_REQUEST_OBJECT)\n        .fallbackToDefault(true)\n        .askForGooglePlayServices(false)\n        .askForSettingsApi(true)\n        .failOnConnectionSuspended(true)\n        .failOnSettingsApiSuspended(false)\n        .ignoreLastKnowLocation(false)\n        .setWaitPeriod(20 * 1000)\n        .build())\n    .useDefaultProviders(new DefaultProviderConfiguration.Builder()\n        .requiredTimeInterval(5 * 60 * 1000)\n        .requiredDistanceInterval(0)\n        .acceptableAccuracy(5.0f)\n        .acceptableTimePeriod(5 * 60 * 1000)\n        .gpsMessage(\"Turn on GPS?\")\n        .gpsDialogProvider(new YourCustomDialogProvider())\n        .setWaitPeriod(ProviderType.GPS, 20 * 1000)\n        .setWaitPeriod(ProviderType.NETWORK, 20 * 1000)\n        .build())\n    .build();\n```\n\nLibrary is modular enough to let you create your own way for Permission request, Dialog display, or even a whole LocationProvider process. (Custom LocationProvider implementation is described below in LocationManager section)\n\nYou can create your own [PermissionProvider][7] implementation and simply set it to [PermissionConfiguration][8], and then library will use your implementation. Your custom PermissionProvider implementation will receive your configuration requirements from PermissionConfiguration object once it's built. If you don't specify any PermissionProvider to PermissionConfiguration [DefaultPermissionProvider][9] will be used. If you don't specify PermissionConfiguration to LocationConfiguration [StubPermissionProvider][10] will be used instead.\n\nYou can create your own [DialogProvider][11] implementation to display `rationale message` or `gps request message` to user, and simply set them to required configuration objects. If you don't specify any [SimpleMessageDialogProvider][12] will be used as default.\n\n## LocationManager\n\nOk, we have our configuration object up to requirements, now we need a manager configured with it.\n\n```java\n// LocationManager MUST be initialized with Application context in order to prevent MemoryLeaks\nLocationManager awesomeLocationManager = new LocationManager.Builder(getApplicationContext())\n    .activity(activityInstance) // Only required to ask permission and/or GoogleApi - SettingsApi\n    .fragment(fragmentInstance) // Only required to ask permission and/or GoogleApi - SettingsApi\n    .configuration(awesomeConfiguration)\n    .locationProvider(new YourCustomLocationProvider())\n    .notify(new LocationListener() { ... })\n    .build();\n```\n\nLocationManager doesn't keep strong reference of your activity **OR** fragment in order not to cause any memory leak. They are required to ask for permission and/or GoogleApi - SettingsApi in case they need to be resolved.\n\nYou can create your own [LocationProvider][13] implementation and ask library to use it. If you don't set any, library will use [DispatcherLocationProvider][14], which will do all the stuff is described above, as default.\n\nEnough, gimme the location now!\n\n```java\nawesomeLocationManager.get();\n```\n\nDone! Enjoy :)\n\n## Logging\n\nLibrary has a lot of log implemented, in order to make tracking the process easy, you can simply enable or disable it.\nIt is highly recommended to disable in release mode.\n\n```java \nLocationManager.enableLog(false);\n```\n\nFor a more fine tuned logging, you can provide a custom Logger implementation to filter and delegate logs as you need it.\n\n```java\nLogger myCustomLoggerImplementation = new MyCustomLoggerImplementation();\nLocationManager.setLogger(myCustomLoggerImplementation);\n```\n\n## Restrictions\nIf you are using LocationManager in a\n- Fragment, you need to redirect your `onActivityResult` to fragment manually, because GooglePlayServices Api and SettingsApi calls `startActivityForResult` from activity. For the sample implementation please see [SampleFragmentActivity][15].\n- Service, you need to have the permission already otherwise library will fail immediately with PermissionDenied error type. Because runtime permissions can be asked only from a fragment or an activity, not from a context. For the sample implementation please see [SampleService][16].\n\n## AndroidManifest\n\nLibrary requires 3 permission;\n - 2 of them `ACCESS_NETWORK_STATE` and `INTERNET` are not in `Dangerous Permissions` and they are required in order to use Network Provider. So if your configuration doesn't require them, you don't need to define them, otherwise they need to be defined.\n - The other one is `ACCESS_FINE_LOCATION` and it is marked as `Dangerous Permissions`, so you need to define it in Manifest and library will ask runtime permission for that if the application is running on Android M or higher OS  version. If you don't specify in Manifest, library will fail immediately with PermissionDenied when location is required.\n\n```html\n\u003cuses-permission android:name=\"android.permission.ACCESS_NETWORK_STATE\" /\u003e\n\u003cuses-permission android:name=\"android.permission.INTERNET\" /\u003e\n\n\u003cuses-permission android:name=\"android.permission.ACCESS_FINE_LOCATION\" /\u003e\n\u003cuses-permission android:name=\"android.permission.ACCESS_COARSE_LOCATION\" /\u003e\n```\n\nYou might also need to consider information below from [the location guide page.][17]\n\n\u003cblockquote\u003e\n\u003cb\u003eCaution:\u003c/b\u003e If your app targets Android 5.0 (API level 21) or higher, you must declare that your app uses the android.hardware.location.network or android.hardware.location.gps hardware feature in the manifest file, depending on whether your app receives location updates from NETWORK_PROVIDER or from GPS_PROVIDER. If your app receives location information from either of these location provider sources, you need to declare that the app uses these hardware features in your app manifest. On devices running versions prior to Android 5.0 (API 21), requesting the ACCESS_FINE_LOCATION or ACCESS_COARSE_LOCATION permission includes an implied request for location hardware features. However, requesting those permissions does not automatically request location hardware features on Android 5.0 (API level 21) and higher.\n\u003c/blockquote\u003e\n\n## Download\nAdd library dependency to your `build.gradle` file:\n\n```groovy\ndependencies {    \n     implementation 'com.yayandroid:LocationManager:x.y.z'\n}\n```\n\n## License\n```\nCopyright 2016 yayandroid\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n   http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n\n[1]: https://developers.google.com/android/reference/com/google/android/gms/location/FusedLocationProviderClient\n[2]: https://github.com/yayaa/LocationManager/blob/master/library/src/main/java/com/yayandroid/locationmanager/base/LocationBaseActivity.java\n[3]: https://github.com/yayaa/LocationManager/blob/master/library/src/main/java/com/yayandroid/locationmanager/base/LocationBaseFragment.java\n[4]: https://github.com/yayaa/LocationManager/blob/master/library/src/main/java/com/yayandroid/locationmanager/base/LocationBaseService.java\n[5]: https://github.com/yayaa/LocationManager/tree/master/app\n[6]: https://github.com/yayaa/LocationManager/blob/master/library/src/main/java/com/yayandroid/locationmanager/configuration/Configurations.java\n[7]: https://github.com/yayaa/LocationManager/blob/master/library/src/main/java/com/yayandroid/locationmanager/providers/permissionprovider/PermissionProvider.java\n[8]: https://github.com/yayaa/LocationManager/blob/master/library/src/main/java/com/yayandroid/locationmanager/configuration/PermissionConfiguration.java\n[9]: https://github.com/yayaa/LocationManager/blob/master/library/src/main/java/com/yayandroid/locationmanager/providers/permissionprovider/DefaultPermissionProvider.java\n[10]: https://github.com/yayaa/LocationManager/blob/master/library/src/main/java/com/yayandroid/locationmanager/providers/permissionprovider/StubPermissionProvider.java\n[11]: https://github.com/yayaa/LocationManager/blob/master/library/src/main/java/com/yayandroid/locationmanager/providers/dialogprovider/DialogProvider.java\n[12]: https://github.com/yayaa/LocationManager/blob/master/library/src/main/java/com/yayandroid/locationmanager/providers/dialogprovider/SimpleMessageDialogProvider.java\n[13]: https://github.com/yayaa/LocationManager/blob/master/library/src/main/java/com/yayandroid/locationmanager/providers/locationprovider/LocationProvider.java\n[14]: https://github.com/yayaa/LocationManager/blob/master/library/src/main/java/com/yayandroid/locationmanager/providers/locationprovider/DispatcherLocationProvider.java\n[15]: https://github.com/yayaa/LocationManager/blob/master/app/src/main/java/com/yayandroid/locationmanager/sample/fragment/SampleFragmentActivity.java\n[16]: https://github.com/yayaa/LocationManager/blob/master/app/src/main/java/com/yayandroid/locationmanager/sample/service/SampleService.java\n[17]:https://developer.android.com/guide/topics/location/strategies.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyayaa%2FLocationManager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyayaa%2FLocationManager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyayaa%2FLocationManager/lists"}