https://github.com/patloew/colocation
🗺 Coroutines Location APIs Library for Android and Kotlin
https://github.com/patloew/colocation
android android-library coroutines coroutines-android coroutines-flow kotlin kotlin-android location location-services
Last synced: 6 months ago
JSON representation
🗺 Coroutines Location APIs Library for Android and Kotlin
- Host: GitHub
- URL: https://github.com/patloew/colocation
- Owner: patloew
- License: other
- Created: 2020-08-28T10:31:48.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2023-02-09T23:33:39.000Z (over 2 years ago)
- Last Synced: 2025-03-27T20:51:12.242Z (6 months ago)
- Topics: android, android-library, coroutines, coroutines-android, coroutines-flow, kotlin, kotlin-android, location, location-services
- Language: Kotlin
- Homepage:
- Size: 139 KB
- Stars: 121
- Watchers: 1
- Forks: 16
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Coroutines Location API Library for Android
[](https://travis-ci.org/patloew/CoLocation) [](https://codecov.io/gh/patloew/CoLocation) [](https://search.maven.org/search?q=g:%22com.patloew.colocation%22%20AND%20a:%22colocation%22) [](https://android-arsenal.com/api?level=14)
This library wraps the Location APIs in Kotlin coroutines and `Flow`.
# Usage
Create a `CoLocation` or `CoGeocoding` instance, preferably by using a dependency injection framework. `CoLocation` is
very similar to the classes provided by the Location APIs. Instead of `LocationServices.getFusedLocationProviderClient(context).lastLocation`
you can use `coLocation.getLastLocation()`. Make sure to have the Location permission from Marshmallow on, if they are
needed by your API requests.
Example:
```kotlin
val coLocation = CoLocation.from(context);
val coGeocoder = CoGeocoder.from(context);
val locationRequest = LocationRequest.create()
.setPriority(LocationRequest.PRIORITY_HIGH_ACCURACY)
.setInterval(5000)
val locationUpdates: MutableLiveData = MutableLiveData()
val addressUpdates: LiveData
= locationUpdates.switchMap { location ->
liveData { emit(coGeocoder.getAddressFromLocation(location)) }
}
val job = viewModelScope.launch {
try {
coLocation.getLocationUpdates(locationRequest).collect(mutableLocationUpdates::postValue)
} catch (e: CancellationException) {
// Location updates cancelled
}
}
// The updates get canceled automatically when viewModelScope is cancelled.
// If you want to cancel it before that, save the job and cancel it.
job.cancel()
```
The following APIs are wrapped by this library:
* `FusedLocationProviderClient` via `CoLocation`
* `SettingsClient` via `CoLocation`
* `Geocoder` via `CoGeocoder`
Checking the location settings is simplified with this library, by providing a `SettingsResult` via
`coLocation.checkLocationSettings(locationRequest)`:
```kotlin
val settingsResult = coLocation.checkLocationSettings(locationRequest)
when (settingsResult) {
SettingsResult.Satisfied -> startLocationUpdates()
is SettingsResult.Resolvable -> settingsResult.resolve(activity, REQUEST_SHOW_SETTINGS)
else -> { /* Ignore for now, we can't resolve this anyway */ }
}
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
super.onActivityResult(requestCode, resultCode, data)
if (requestCode == REQUEST_SHOW_SETTINGS && resultCode == Activity.RESULT_OK) {
// Resolution success, location settings are now satisfied
startLocationUpdates()
}
}
```
# Sample
A basic sample app is available in the `sample` project.
# Setup
The library is available on Maven Central. Add the following to your `build.gradle`:
```groovy
dependencies {
implementation 'com.patloew.colocation:colocation:1.1.1'
implementation 'com.google.android.gms:play-services-location:21.0.1'
}
```
If you want to use a newer version of Google Play Services, declare the newer version in your `build.gradle`. This then
overrides the version declared in the library.
CoLocation only works with Android Gradle Plugin 3.0.0 or higher, since it uses Java 8 language features. Don't forget
to set the source code compatibility to Java 8:
```groovy
android {
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
kotlinOptions {
jvmTarget = "1.8"
}
}
```
# Testing
When unit testing your app's classes, `CoLocation` and `CoGeocoder` behavior can be mocked easily. See
`MainViewModelTest` in the `sample` project for an example test.
# Donations
If you like the library and want to support the creator for development/maintenance, you can make a donation in Bitcoin
to `bc1q5uejfyl2kskhhveg7lx4fcwgv8hz88r92yzjsu`. Thank you!
# License
Copyright 2020 Patrick Löwenstein
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.