Lightweight asynchronous solution fetching accurate GPS coordinates and reverse-geocoding into localized, human-readable addresses; includes smart throttling, dynamic language localization, and robust error handling.
A lightweight, modern, and coroutine-based Kotlin Multiplatform (KMP) library designed to effortlessly fetch precise GPS coordinates and seamlessly reverse-geocode them into localized, human-readable street addresses.
GeoLocation-Kmp is built with resilience in mind. It abstracts away the complex boilerplate of platform-specific location services and gracefully handles, rate-limiting, and network errors—ensuring your app remains stable and responsive.
Add the dependency to your commonMain source set in your build.gradle.kts file:
kotlin {
sourceSets {
commonMain.dependencies {
implementation("io.github.mamon-aburawi:geolocation-kmp:{last_version}")
}
}
}
Before requesting the user's location, you must configure the native permissions for both Android and iOS.
Add the following permissions to your android/src/main/AndroidManifest.xml file.
Note: Because this library uses OpenStreetMap for reverse geocoding, the INTERNET permission is also required.
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-permission android:name="android.permission.INTERNET"/>
Apple strictly requires apps to explain why they need the user's location. You must add the following key to your iOS app's iosApp/iosApp/Info.plist file. If this is missing, iOS will instantly crash your app when a location request is made.
<key>NSLocationWhenInUseUsageDescription</key>
<string>We need your location to show your current address.</string>
Since desktop environments typically lack native GPS hardware and location services, the location on Desktop targets is retrieved using the device's IP address. No explicit OS permissions are required to be configured.
The library provides a simple, unified GeoLocation interface. Note: OpenStreetMap policy strictly requires you to provide an email or agent name to identify your app during geocoding requests.
For Compose, you can create a rememberGeoLocation state helper so your class survives recompositions.
val geoLocation = rememberGeoLocation(agentName = "your@email.com", languageCode = "en")
scope.launch {
val location = geoLocation.findLocation()
println("Address: ${location?.fullAddress}")
}
private val geoLocation = GeoLocation(
email = "your-contact-email@example.com",
languageCode = "en" // Try "ar" for Arabic or "es" for Spanish!
)
scope.launch {
val location = geoLocation.findLocation()
println("Address: ${location?.fullAddress}")
}
This library uses the free, public OpenStreetMap (Nominatim) server for reverse geocoding. By using this library, you agree to their Usage Policy.
email (or app identifier) to the GeoLocation class. This is used in the User-Agent header. Using a random or blank string will result in a permanent IP ban from OpenStreetMap.If you find this repo useful, please support me by leaving a ⭐!
| Feature | Description |
|---|
| 🌐 True Multiplatform | Full support for Android, iOS, Desktop, and Web. Write your location logic once and run it anywhere. |
| 🌍 Dynamic Localization | Pass ISO language codes (like "en", "ar") to dynamically localize the street address results. |
| 🚦 Smart Throttling | Built-in debouncer prevents API spam, protecting your application from bans and handling HTTP 429 (Rate Limit) errors automatically. |
Surfaced from shared tags and platforms — no rankings paid for.