BigDataCloud Kotlin Client

Official Kotlin/Android client for BigDataCloud free APIs — reverse geocoding and roaming detection.

No API key required. Uses api.bigdatacloud.net.

Looking for full-featured server-side Kotlin SDK with all BigDataCloud APIs? Use the Java SDK which is fully Kotlin-compatible.

Installation

Add to your app's build.gradle.kts:

dependencies {
    implementation("com.bigdatacloud:bigdatacloud-client:1.0.0")
}

Permissions

Add to your AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

And request permissions at runtime before calling reverseGeocode().

Quick Start

val client = BigDataCloudClient(context)

// In a coroutine or ViewModel:
lifecycleScope.launch {
    val result = client.reverseGeocode()
    println("${result.response.city}, ${result.response.countryName}")
    println("Accuracy: ${result.accuracy}") // FINE, COARSE, or IP_BASED
}

Location Strategy

The client follows a strict three-tier location priority:

1. FINE (GPS) — PRIORITY_HIGH_ACCURACY via FusedLocationProviderClient. Always requested first.
2. COARSE (network/cell) — PRIORITY_BALANCED_POWER_ACCURACY. Used when FINE is unavailable.
3. IP_BASED — No coordinates. Server uses caller's IP. Only when all location is denied.

Always show the user what accuracy level is in use:

val result = client.reverseGeocode()

val label = when (result.accuracy) {
    AccuracyLevel.FINE    -> "GPS location"
    AccuracyLevel.COARSE  -> "Approximate location"
    AccuracyLevel.IP_BASED -> "IP-based — enable location for better accuracy"
}

Roaming Detection

val roaming = client.amIRoaming()
if (roaming.isRoaming == true) {
    println("Roaming in ${roaming.roamingCountryName}")
    println("Home: ${roaming.simRegisteredCountryName}")
}

Fair Use Policy

This library uses api.bigdatacloud.net, governed by BigDataCloud's Free Client-Side API Fair Use Policy.

Key rules:

• Client-side only. Requests must originate from the device whose location is being resolved.
• Real-time coordinates only. Only the current, live location of the calling device is permitted. Pre-stored, cached, or externally-sourced coordinates are not allowed.
• User consent required. Coordinates must be obtained via platform geolocation APIs (GPS/WiFi) with the user's permission.

Violations result in a 402 error and IP ban.

If your use case doesn't fit — for example you already have coordinates from another source — use the server-side reverse geocoding API instead. It includes 50,000 free queries per month with an API key.

Requirements

• Android API 21+
• Kotlin coroutines
• Google Play Services Location

License

MIT — see LICENSE.