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.

1. Email Required: You must pass a valid 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.
2. Rate Limits: The API is strictly limited to 1 request per second. This library implements an internal 2-second throttle to protect your app from throwing HTTP 429 Rate Limit errors if the user spams the location button.

If you find this repo useful, please support me by leaving a ⭐!