{"id":15029097,"url":"https://github.com/mrmans0n/smart-location-lib","last_synced_at":"2025-05-14T19:09:50.303Z","repository":{"id":8933143,"uuid":"10664576","full_name":"mrmans0n/smart-location-lib","owner":"mrmans0n","description":"Android library project that lets you manage the location updates to be as painless as possible","archived":false,"fork":false,"pushed_at":"2023-12-15T11:59:32.000Z","size":882,"stargazers_count":1648,"open_issues_count":122,"forks_count":352,"subscribers_count":79,"default_branch":"master","last_synced_at":"2025-04-13T13:59:23.976Z","etag":null,"topics":["activity","android","android-library","geofences","location"],"latest_commit_sha":null,"homepage":"","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/mrmans0n.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,"roadmap":null,"authors":null}},"created_at":"2013-06-13T11:14:18.000Z","updated_at":"2025-03-27T03:56:12.000Z","dependencies_parsed_at":"2024-01-07T06:49:57.161Z","dependency_job_id":"9464d0db-53a7-4a26-8133-c2d4890e9486","html_url":"https://github.com/mrmans0n/smart-location-lib","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrmans0n%2Fsmart-location-lib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrmans0n%2Fsmart-location-lib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrmans0n%2Fsmart-location-lib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrmans0n%2Fsmart-location-lib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mrmans0n","download_url":"https://codeload.github.com/mrmans0n/smart-location-lib/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254209859,"owners_count":22032897,"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":["activity","android","android-library","geofences","location"],"created_at":"2024-09-24T20:09:43.520Z","updated_at":"2025-05-14T19:09:48.123Z","avatar_url":"https://github.com/mrmans0n.png","language":"Java","funding_links":[],"categories":["Maps"],"sub_categories":[],"readme":"Smart Location Library\n======================\n\n[![Android Arsenal](https://img.shields.io/badge/Android%20Arsenal-Smart%20Location%20Library-brightgreen.svg?style=flat)](https://android-arsenal.com/details/1/1321) [![Build Status](https://travis-ci.org/mrmans0n/smart-location-lib.svg?branch=master)](https://travis-ci.org/mrmans0n/smart-location-lib)\n\nAndroid library project that intends to simplify the usage of location providers and activity recognition with a nice fluid API.\n\n**Supported Android versions**: Android 4.0+\n\nAdding to your project\n----------------------\n\nYou should add this to your dependencies:\n\n```groovy\nimplement 'io.nlopez.smartlocation:library:3.3.3'\n```\n\nGoogle Play Services compatible version: 11.4.2\n\nIf you want the rxjava wrappers, these are now in a separate dependency. Just add this new dependency as well:\n\n```groovy\nimplement 'io.nlopez.smartlocation:rx:3.3.3'\n```\n\nIf you got any problem compiling, please check the Common Issues section at the bottom of this document.\n\n## Location\n\n### Starting\n\nFor starting the location service:\n\n````java\nSmartLocation.with(context).location()\n    .start(new OnLocationUpdatedListener() { ... });\n````\n\nIf you just want to get a single location (not periodic) you can just use the oneFix modifier. Example:\n\n````java\nSmartLocation.with(context).location()\n    .oneFix()\n    .start(new OnLocationUpdatedListener() { ... });\n````\n\n### Stopping\n\nFor stopping the location just use the stop method.\n\n````java\nSmartLocation.with(context).location().stop();\n````\n\n### Status\n\nYou can get some information about the current status of location providers to know if you will be able to use the location providers.\n\n````java\n// Check if the location services are enabled\nSmartLocation.with(context).location().state().locationServicesEnabled();\n\n// Check if any provider (network or gps) is enabled\nSmartLocation.with(context).location().state().isAnyProviderAvailable();\n\n// Check if GPS is available\nSmartLocation.with(context).location().state().isGpsAvailable();\n\n// Check if Network is available\nSmartLocation.with(context).location().state().isNetworkAvailable();\n\n// Check if the passive provider is available\nSmartLocation.with(context).location().state().isPassiveAvailable();\n\n// Check if the location is mocked\nSmartLocation.with(context).location().state().isMockSettingEnabled();\n````\n\n### Location strategy\n\nThere are three presets for location parameters:\n\n* `LocationParams.BEST_EFFORT` (default)\n* `LocationParams.NAVIGATION`\n* `LocationParams.LAZY`\n\nYou can change it (if you want one other than the default one) by using the `config(locationParams)` modifier.\n\nIf you want to add some custom parameters for the distances or times involved in the location strategy, you can create your own LocationParams class.\n\n### Changing providers\n\nThere are some providers shipped with the library.\n\n* `LocationGooglePlayServicesWithFallbackProvider` (default). This one will use the Fused Location Provider if it's present, or the LocationManager as fallback if it's not.\n* `LocationGooglePlayServicesProvider` This will use the Fused Location Provider.\n* `LocationManagerProvider` This is the legacy implementation that uses LocationManager.\n* `LocationBasedOnActivityProvider` This allows you to use the activity recognition system to modify the location strategy depending on the activity changes (if the user is walking, running, on a car, a bike...).\n* `MultiFallbackLocationProvider` This lets you create your own \"fallback provider\" if the underlying location service is not available. See \"Multiple Fallback Provider\" below for details.\n\nYou can implement your own if you want. That's ideal if you wanted to use a mock one for testing or something like that, or add support to another possible provider.\n\nExample:\n\n````java\nSmartLocation.with(context).location(new LocationBasedOnActivityProvider(callback))\n    .start(new OnLocationUpdatedListener() { ... });\n````\n\n### Multiple Fallback Provider\n\nThe `MultiFallbackProvider` lets you create your own provider that utilizes multiple underlying location services.\nThe provider will use the location services in the order in which they are added to its `Builder`, which has convenience methods for setting up the Google Play Services provider and the default `LocationManager` provider.\nProviders must implement the `ServiceLocationProvider` interface to enable the fallback behavior.\nExample:\n\n````java\nLocationProvider myProvider = new MyLocationProvider();\nLocationProvider fallbackProvider = new MultiFallbackProvider.Builder()\n    .withGooglePlayServicesProvider().withProvider(myProvider).build();\n````\n\n## Activity\n\n### Starting\n\nFor starting the activity recognition service, you should run:\n\n````java\nSmartLocation.with(context).activityRecognition()\n    .start(new OnActivityUpdatedListener() { ... });\n````\n\n### Stopping\n\nFor stopping the activity recognition you could use the stop method.\n\n````java\nSmartLocation.with(context).activityRecognition().stop();\n````\n\n## Geofencing\n\nWe can add geofences and receive the information when we enter, exit or dwell in a Geofence. The geofences are defined by a GeofenceModel, and you should use the requestId as a identifier.\n\nWe can add and remove geofences with a similar syntax as all the others.\n\n````java\nGeofenceModel mestalla = new GeofenceModel.Builder(\"id_mestalla\")\n    .setTransition(Geofence.GEOFENCE_TRANSITION_ENTER)\n    .setLatitude(39.47453120000001)\n    .setLongitude(-0.358065799999963)\n    .setRadius(500)\n    .build();\n\nGeofenceModel cuenca = new GeofenceModel.Builder(\"id_cuenca\")\n    .setTransition(Geofence.GEOFENCE_TRANSITION_EXIT)\n    .setLatitude(40.0703925)\n    .setLongitude(-2.1374161999999615)\n    .setRadius(2000)\n    .build();\n\nSmartLocation.with(context).geofencing()\n    .add(mestalla)\n    .add(cuenca)\n    .remove(\"already_existing_geofence_id\")\n    .start(new OnGeofencingTransitionListener() { ... });\n````\n\nIf you want to capture the Geofence transitions without the app running, you can hook up a BroadcastReceiver to the intent action stored in the `GeofencingGooglePlayServicesProvider.BROADCAST_INTENT_ACTION` constant. The intent will come with the geofence, the location and the type of transition within the bundle.\n\n## Geocoding\n\nThe library has support for direct geocoding (aka getting a Location object based on a String) and reverse geocoding (getting the Street name based on a Location object).\n\nThere are pretty basic calls in the API for both operations separatedly.\n\n### Direct geocoding\n````java\nSmartLocation.with(context).geocoding()\n    .direct(\"Estadi de Mestalla\", new OnGeocodingListener() {\n        @Override\n        public void onLocationResolved(String name, List\u003cLocationAddress\u003e results) {\n            // name is the same you introduced in the parameters of the call\n            // results could come empty if there is no match, so please add some checks around that\n            // LocationAddress is a wrapper class for Address that has a Location based on its data\n            if (results.size() \u003e 0) {\n            \tLocation mestallaLocation = results.get(0).getLocation();\n            \t// [...] Do your thing! :D\n            }\n        }\n    });\n````\n\n### Reverse geocoding\n````java\nSmartLocation.with(context).geocoding()\n    .reverse(location, new OnReverseGeocodingListener() {\n        @Override\n        public onAddressResolved(Location original, List\u003cAddress\u003e results) {\n            // ...\n        }\n    });\n````\n\n### Mixing things up\n\nBut we can mix and batch those requests, if needed. Also, you can provide the number of maximum possible matches you want to receive for each one of the lookups separatedly.\n\n````java\nLocation myLocation1 = new Location(...);\n\nSmartLocation.with(context).geocoding()\n    .add(\"Estadi de Mestalla\", 5)\n    .add(\"Big Ben\", 2)\n    .add(myLocation1, 4)\n    .start(directGeocodingListener, reverseGeocodingListener);\n````\n\nThis will launch a new call to the callbacks everytime one of the geofence lookups is resolved.\n\n### Stopping\n\nYou should invoke the stop method whenever the calling activity/fragment or whatever is going to be destroyed, for cleanup purposes.\n\n## RxJava / RxAndroid support\n\nThe wrappers to rxjava2 are located in this package.\n\n```groovy\nimplement 'io.nlopez.smartlocation:rx:3.3.1'\n```\n\nYou can wrap the calls with ObservableFactory methods to retrieve an Observable object. You won't need to call start, just subscribe to the observable to get the updates.\n\nFor example, for location:\n\n```java\nObservable\u003cLocation\u003e locationObservable = ObservableFactory.from(SmartLocation.with(context).location());\nlocationObservable.subscribe(new Action1\u003cLocation\u003e() {\n    @Override\n    public void call(Location location) {\n        // Do your stuff here :)\n    }\n});\n```\n\nCommon issues\n-------------\n\nIf you are already using Google Play Services in your project and have problems compiling, you can try setting the transitive property to false:\n\n```groovy\nimplement ('io.nlopez.smartlocation:library:3.3.3') {\n\ttransitive = false\n}\n```\n\nIf you got an error in the manifest merging, like this one: \n\n```\n\u003e Manifest merger failed : Attribute meta-data#com.google.android.gms.version@value value=(@integer/google_play_services_version) from AndroidManifest.xml:44:13\n    is also present at io.nlopez.smartlocation:library:3.0.5:28:13 value=(6587000)\n    Suggestion: add 'tools:replace=\"android:value\"' to \u003cmeta-data\u003e element at AndroidManifest.xml:42:9 to override\n\n\n    Error:(46, 13) Attribute meta-data#com.google.android.gms.version@value value=(@integer/google_play_services_version) from AndroidManifest.xml:46:13\n```\n\nIf you follow the suggestion provided, you can get rid of it easily. Just change in your manifest the meta-data tag with the google play services version, like this:\n\n```xml\n\u003cmeta-data tools:replace=\"android:value\" android:name=\"com.google.android.gms.version\" android:value=\"@integer/google_play_services_version\" /\u003e\n```\n\nContributing\n------------\nForks, patches and other feedback are welcome.\n\nCreators\n--------\n\nNacho López @mrmans0n\n\nLicense\n-------\n\nThe MIT License (MIT)\n\nCopyright (c) 2013-2017 Nacho Lopez\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\nTHE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrmans0n%2Fsmart-location-lib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmrmans0n%2Fsmart-location-lib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrmans0n%2Fsmart-location-lib/lists"}