Unified Network Location Provider (UnifiedNlp)

UnifiedNlp acts as a middleware layer and does not provide geolocation features on its own. To enable location services, you must install one or more backends (plugins). Backends can typically be found and updated via F-Droid.

Geolocation Backends

• AppleWifiNlpBackend: Uses Apple's service for Wi-Fi resolution.
• OpenBmapNlpBackend: Uses openBmap (freely licensed, supports offline use).
• MozillaNlpBackend: Uses Mozilla Location Service.
• LocalGSMBackend: Local provider for GSM cells (works offline).
• LocalWifiNlpBackend: Local provider using on-phone generated Wi-Fi database.

(Reverse) Geocoding Backends

• NominatimGeocoderBackend: Address lookup backend.

Activation

After installing a backend, activate it in Android settings:

• Android 4.4+: Go to Settings -> Location and select any mode except "device only".
• Older Android: Go to Settings -> Location -> Wi-Fi & mobile network location.

The GeocodeClient provides an interface to interact with geocoding and reverse geocoding services. It supports both synchronous calls and Kotlin coroutines (suspend functions). It requires an Android Context and a Lifecycle object for initialization.

Available Methods

Geocoding (Address to Coordinates)

• requestGeocodeSync(request: GeocodeRequest, options: Bundle = defaultOptions): List<Address>: Synchronous call to retrieve addresses based on a geocode request.
• suspend requestGeocode(request: GeocodeRequest, options: Bundle = defaultOptions): List<Address>: Asynchronous coroutine-based call to retrieve addresses.

Reverse Geocoding (Coordinates to Address)

• requestReverseGeocodeSync(request: ReverseGeocodeRequest, options: Bundle = defaultOptions): List<Address>: Synchronous call to retrieve addresses based on a reverse geocode request.
• suspend requestReverseGeocode(request: ReverseGeocodeRequest, options: Bundle = defaultOptions): List<Address>: Asynchronous coroutine-based call to retrieve addresses.

Backend Management

• suspend getGeocodeBackends(options: Bundle = defaultOptions): List<String>: Retrieves a list of available geocode backends.
• suspend setGeocodeBackends(backends: List<String>, options: Bundle = defaultOptions): Unit: Sets the active geocode backends.

// Example usage of GeocodeClient
val client = GeocodeClient(context, lifecycle)

// Asynchronous geocoding
val addresses = client.requestGeocode(geocodeRequest)

// Asynchronous reverse geocoding
val reverseAddresses = client.requestReverseGeocode(reverseGeocodeRequest)

// Managing backends
val backends = client.getGeocodeBackends()
client.setGeocodeBackends(listOf("backend_name"))

To implement a custom geocoding provider within the UnifiedNLP framework, extend the GeocodeProvider class. You must override the following core methods to handle geocoding and reverse geocoding requests:

• onGetFromLocation: Performs reverse geocoding (converting coordinates to an address) using latitude, longitude, maxResults, params (containing locale and clientPackage), and a mutable list of Address objects to populate.
• onGetFromLocationName: Performs forward geocoding (converting a name to coordinates/address) using the locationName, a bounding box defined by lowerLeftLatitude/lowerLeftLongitude and upperRightLatitude/upperRightLongitude, maxResults, and params.

Note that the implementation provided in this source uses a GeocodeClient to perform synchronous requests (requestReverseGeocodeSync and requestGeocodeSync) and populates the provided addrs list.

class MyCustomGeocodeProvider(context: Context, lifecycle: Lifecycle) : GeocodeProvider() {

    override fun onGetFromLocation(
        latitude: Double, 
        longitude: Double, 
        maxResults: Int, 
        params: GeocoderParams, 
        addrs: MutableList<Address>
    ): String? {
        // Implementation logic
        return null
    }

    override fun onGetFromLocationName(
        locationName: String?, 
        lowerLeftLatitude: Double, 
        lowerLeftLongitude: Double, 
        upperRightLatitude: Double, 
        upperRightLongitude: Double, 
        maxResults: Int, 
        params: GeocoderParams, 
        addrs: MutableList<Address>
    ): String? {
        // Implementation logic
        return null
    }
}

The deprecated UnifiedLocationClient provides geocoding capabilities (converting coordinates to addresses or names to coordinates):

• getFromLocation(latitude, longitude, maxResults, locale, timeout): A suspend function to get addresses from coordinates.
• getFromLocationSync(...): A synchronous version of the above.
• getFromLocationName(locationName, maxResults, lowerLeftLat, lowerLeftLong, upperRightLat, upperRightLong, locale, timeout): A suspend function to get addresses from a location name within a bounding box.
• getFromLocationNameSync(...): A synchronous version of the above.

// Get addresses from coordinates
val addresses = client.getFromLocation(
    latitude = 52.52, 
    longitude = 13.40, 
    maxResults = 1, 
    locale = "en"
)

// Get addresses from a name
val addressesByName = client.getFromLocationName(
    locationName = "Berlin",
    maxResults = 5,
    lowerLeftLatitude = 52.0,
    lowerLeftLongitude = 13.0,
    upperRightLatitude = 53.0,
    upperRightLongitude = 14.0,
    locale = "en"
)