Add support for location-based filtering

Author: gpunto

stream-android-core/src/main/java/io/getstream/android/core/api/filter/Filter.kt

@@ -18,6 +18,9 @@ package io.getstream.android.core.api.filter
 
 import io.getstream.android.core.annotations.StreamInternalApi
 import io.getstream.android.core.annotations.StreamPublishedApi
+import io.getstream.android.core.api.model.location.BoundingBox
+import io.getstream.android.core.api.model.location.CircularRegion
+import io.getstream.android.core.api.model.location.toRequestMap
 import io.getstream.android.core.internal.filter.BinaryOperator
 import io.getstream.android.core.internal.filter.CollectionOperator
 import io.getstream.android.core.internal.filter.FilterOperations
@@ -45,11 +48,19 @@ internal data class CollectionOperationFilter<M, F : FilterField<M>>(
 @StreamInternalApi
 public fun Filter<*, *>.toRequest(): Map<String, Any> =
     when (this) {
-        is BinaryOperationFilter<*, *> -> mapOf(field.remote to mapOf(operator.remote to value))
+        is BinaryOperationFilter<*, *> ->
+            mapOf(field.remote to mapOf(operator.remote to value.toRequestValue()))
         is CollectionOperationFilter<*, *> ->
             mapOf(operator.remote to filters.map(Filter<*, *>::toRequest))
     }
 
+private fun Any.toRequestValue() =
+    when (this) {
+        is CircularRegion -> toRequestMap()
+        is BoundingBox -> toRequestMap()
+        else -> this
+    }
+
 /** Checks if this filter matches the given item. */
 @StreamInternalApi
 public infix fun <M, F : FilterField<M>> Filter<M, F>.matches(item: M): Boolean =
@@ -71,8 +82,10 @@ public infix fun <M, F : FilterField<M>> Filter<M, F>.matches(item: M): Boolean
                     BinaryOperator.QUERY -> notNull && search(filterValue, where = fieldValue)
                     BinaryOperator.AUTOCOMPLETE -> notNull && fieldValue autocompletes filterValue
                     BinaryOperator.EXISTS -> fieldValue exists filterValue
-                    BinaryOperator.CONTAINS -> notNull && fieldValue contains filterValue
+                    BinaryOperator.CONTAINS -> notNull && fieldValue doesContain filterValue
                     BinaryOperator.PATH_EXISTS -> notNull && fieldValue containsPath filterValue
+                    BinaryOperator.NEAR -> notNull && fieldValue near filterValue
+                    BinaryOperator.WITHIN_BOUNDS -> notNull && fieldValue withinBounds filterValue
                 }
             }
         }

stream-android-core/src/main/java/io/getstream/android/core/api/filter/Filters.kt

@@ -17,6 +17,8 @@
 package io.getstream.android.core.api.filter
 
 import io.getstream.android.core.annotations.StreamPublishedApi
+import io.getstream.android.core.api.model.location.BoundingBox
+import io.getstream.android.core.api.model.location.CircularRegion
 import io.getstream.android.core.internal.filter.BinaryOperator
 import io.getstream.android.core.internal.filter.CollectionOperator
 
@@ -171,3 +173,30 @@ public fun <M, F : FilterField<M>> F.contains(value: Any): Filter<M, F> =
 @StreamPublishedApi
 public fun <M, F : FilterField<M>> F.pathExists(value: String): Filter<M, F> =
     BinaryOperationFilter(BinaryOperator.PATH_EXISTS, this, value)
+
+/**
+ * Creates a filter that uses the Haversine formula to find values within the specified distance
+ * from the given coordinates.
+ *
+ * This filter matches locations that fall within a circular region defined by a center point and a
+ * radius. The distance calculation uses the Haversine formula to account for Earth's curvature.
+ *
+ * @param region The circular region defining the center point and radius to match against.
+ * @return A filter that matches when the location field is within the specified circular region.
+ */
+@StreamPublishedApi
+public fun <M, F : FilterField<M>> F.near(region: CircularRegion): Filter<M, F> =
+    BinaryOperationFilter(BinaryOperator.NEAR, this, region)
+
+/**
+ * Creates a filter that finds values within the specified rectangular bounding box.
+ *
+ * This filter matches locations that fall within a rectangular geographic region defined by
+ * northeast and southwest corner coordinates.
+ *
+ * @param boundingBox The bounding box defining the rectangular region to match against.
+ * @return A filter that matches when the location field is within the specified bounding box.
+ */
+@StreamPublishedApi
+public fun <M, F : FilterField<M>> F.withinBounds(boundingBox: BoundingBox): Filter<M, F> =
+    BinaryOperationFilter(BinaryOperator.WITHIN_BOUNDS, this, boundingBox)

stream-android-core/src/main/java/io/getstream/android/core/api/model/location/BoundingBox.kt

@@ -0,0 +1,50 @@
+/*
+ * Copyright (c) 2014-2025 Stream.io Inc. All rights reserved.
+ *
+ * Licensed under the Stream License;
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    https://github.com/GetStream/stream-core-android/blob/main/LICENSE
+ *
+ * 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.
+ */
+
+package io.getstream.android.core.api.model.location
+
+import io.getstream.android.core.annotations.StreamPublishedApi
+
+/**
+ * A rectangular geographic region defined by northeast and southwest corner coordinates.
+ *
+ * @param northeast The northeast (top-right) corner coordinate of the bounding box.
+ * @param southwest The southwest (bottom-left) corner coordinate of the bounding box.
+ */
+@StreamPublishedApi
+public data class BoundingBox(val northeast: LocationCoordinate, val southwest: LocationCoordinate)
+
+/**
+ * Checks if the specified coordinate is within this bounding box.
+ *
+ * @param coordinate The coordinate to check.
+ * @return True if the coordinate is within the bounding box, false otherwise.
+ */
+internal operator fun BoundingBox.contains(coordinate: LocationCoordinate): Boolean {
+    return coordinate.latitude >= southwest.latitude &&
+        coordinate.latitude <= northeast.latitude &&
+        coordinate.longitude >= southwest.longitude &&
+        coordinate.longitude <= northeast.longitude
+}
+
+/** Converts this bounding box to a map representation suitable for API requests. */
+internal fun BoundingBox.toRequestMap(): Map<String, Any> =
+    mapOf(
+        "ne_lat" to northeast.latitude,
+        "ne_lng" to northeast.longitude,
+        "sw_lat" to southwest.latitude,
+        "sw_lng" to southwest.longitude,
+    )

stream-android-core/src/main/java/io/getstream/android/core/api/model/location/CircularRegion.kt

@@ -0,0 +1,54 @@
+/*
+ * Copyright (c) 2014-2025 Stream.io Inc. All rights reserved.
+ *
+ * Licensed under the Stream License;
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    https://github.com/GetStream/stream-core-android/blob/main/LICENSE
+ *
+ * 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.
+ */
+
+package io.getstream.android.core.api.model.location
+
+import android.location.Location
+import io.getstream.android.core.annotations.StreamPublishedApi
+
+/**
+ * A circular geographic region defined by a center point and a radius.
+ *
+ * @param center The center coordinate of the circular region.
+ * @param radius The radius of the circular region.
+ */
+@StreamPublishedApi
+public data class CircularRegion(val center: LocationCoordinate, val radius: Distance)
+
+/**
+ * Checks if the specified coordinate is within this circular region.
+ *
+ * @param coordinate The coordinate to check.
+ * @return True if the coordinate is within the region, false otherwise.
+ */
+internal operator fun CircularRegion.contains(coordinate: LocationCoordinate): Boolean {
+    val centerLocation =
+        Location("").apply {
+            latitude = this@contains.center.latitude
+            longitude = this@contains.center.longitude
+        }
+    val coordinateLocation =
+        Location("").apply {
+            latitude = coordinate.latitude
+            longitude = coordinate.longitude
+        }
+    val distance = centerLocation.distanceTo(coordinateLocation).toDouble()
+    return distance <= this@contains.radius.inMeters
+}
+
+/** Converts this circular region to a map representation suitable for API requests. */
+internal fun CircularRegion.toRequestMap(): Map<String, Any> =
+    mapOf("lat" to center.latitude, "lng" to center.longitude, "distance" to radius.inKilometers)

stream-android-core/src/main/java/io/getstream/android/core/api/model/location/Distance.kt

@@ -0,0 +1,89 @@
+/*
+ * Copyright (c) 2014-2025 Stream.io Inc. All rights reserved.
+ *
+ * Licensed under the Stream License;
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    https://github.com/GetStream/stream-core-android/blob/main/LICENSE
+ *
+ * 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.
+ */
+
+package io.getstream.android.core.api.model.location
+
+import io.getstream.android.core.annotations.StreamPublishedApi
+
+/**
+ * Represents a distance measurement with type safety and automatic unit conversion.
+ *
+ * @param inMeters The distance value stored internally in meters.
+ */
+@JvmInline
+@StreamPublishedApi
+public value class Distance private constructor(public val inMeters: Double) {
+
+    /** Returns the distance value in kilometers. */
+    public val inKilometers: Double
+        get() = inMeters / 1000.0
+
+    internal companion object {
+        fun fromMeters(meters: Double): Distance = Distance(meters)
+    }
+}
+
+/**
+ * Extension property to create a [Distance] from a [Double] value in meters.
+ *
+ * ## Example
+ *
+ * ```kotlin
+ * val distance = 1500.2.meters  // 1500.2 meters
+ * ```
+ */
+@StreamPublishedApi
+public val Double.meters: Distance
+    get() = Distance.fromMeters(this)
+
+/**
+ * Extension property to create a [Distance] from a [Double] value in kilometers.
+ *
+ * ## Example
+ *
+ * ```kotlin
+ * val distance = 1.5.kilometers  // 1.5 kilometers
+ * ```
+ */
+@StreamPublishedApi
+public val Double.kilometers: Distance
+    get() = Distance.fromMeters(this * 1000.0)
+
+/**
+ * Extension property to create a [Distance] from an [Int] value in meters.
+ *
+ * ## Example
+ *
+ * ```kotlin
+ * val distance = 1500.meters  // 1500 meters
+ * ```
+ */
+@StreamPublishedApi
+public val Int.meters: Distance
+    get() = toDouble().meters
+
+/**
+ * Extension property to create a [Distance] from an [Int] value in kilometers.
+ *
+ * ## Example
+ *
+ * ```kotlin
+ * val distance = 5.kilometers  // 5 kilometers
+ * ```
+ */
+@StreamPublishedApi
+public val Int.kilometers: Distance
+    get() = toDouble().kilometers

stream-android-core/src/main/java/io/getstream/android/core/api/model/location/LocationCoordinate.kt

@@ -0,0 +1,30 @@
+/*
+ * Copyright (c) 2014-2025 Stream.io Inc. All rights reserved.
+ *
+ * Licensed under the Stream License;
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    https://github.com/GetStream/stream-core-android/blob/main/LICENSE
+ *
+ * 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.
+ */
+
+package io.getstream.android.core.api.model.location
+
+import io.getstream.android.core.annotations.StreamPublishedApi
+
+/**
+ * Represents a geographic coordinate with latitude and longitude values.
+ *
+ * This class is used to represent location data in geo-spatial filtering operations.
+ *
+ * @param latitude The latitude coordinate in degrees. Must be between -90 and 90.
+ * @param longitude The longitude coordinate in degrees. Must be between -180 and 180.
+ */
+@StreamPublishedApi
+public data class LocationCoordinate(val latitude: Double, val longitude: Double)

stream-android-core/src/main/java/io/getstream/android/core/internal/filter/FilterOperations.kt

@@ -16,6 +16,12 @@
 
 package io.getstream.android.core.internal.filter
 
+import io.getstream.android.core.api.model.location.BoundingBox
+import io.getstream.android.core.api.model.location.CircularRegion
+import io.getstream.android.core.api.model.location.LocationCoordinate
+import io.getstream.android.core.api.model.location.contains
+import io.getstream.android.core.api.model.location.kilometers
+
 internal object FilterOperations {
     infix fun Any.greater(that: Any) = anyCompare(this, that)?.let { it > 0 } == true
 
@@ -47,7 +53,8 @@ internal object FilterOperations {
             else -> false
         }
 
-    infix fun Any.contains(that: Any): Boolean =
+    // Not called "contains" to avoid overloading `Any.contains`, which is too broad
+    infix fun Any.doesContain(that: Any): Boolean =
         when {
             that `in` this -> true
 
@@ -57,7 +64,7 @@ internal object FilterOperations {
                     val thisValue = this[thatKey]
 
                     thisValue == thatValue ||
-                        thisValue != null && thatValue != null && thisValue contains thatValue
+                        thisValue != null && thatValue != null && thisValue doesContain thatValue
                 }
             }
 
@@ -97,4 +104,53 @@ internal object FilterOperations {
 
         return true
     }
+
+    infix fun Any.near(that: Any): Boolean {
+        if (this !is LocationCoordinate) return false
+
+        return when (that) {
+            is CircularRegion -> this in that
+            is Map<*, *> -> {
+                // Handle map format as expected by the API:
+                // { "lat": 41.8904, "lng": 12.4922, "distance": 5.0 }
+                val lat = (that["lat"] as? Number)?.toDouble() ?: return false
+                val lng = (that["lng"] as? Number)?.toDouble() ?: return false
+                val distanceKm = (that["distance"] as? Number)?.toDouble() ?: return false
+
+                val region =
+                    CircularRegion(
+                        center = LocationCoordinate(lat, lng),
+                        radius = distanceKm.kilometers,
+                    )
+                this in region
+            }
+
+            else -> false
+        }
+    }
+
+    infix fun Any.withinBounds(that: Any): Boolean {
+        if (this !is LocationCoordinate) return false
+
+        return when (that) {
+            is BoundingBox -> this in that
+            is Map<*, *> -> {
+                // Handle map format as expected by the API:
+                // { "ne_lat": 41.9200, "ne_lng": 12.5200, "sw_lat": 41.8800, "sw_lng": 12.4700 }
+                val neLat = (that["ne_lat"] as? Number)?.toDouble() ?: return false
+                val neLng = (that["ne_lng"] as? Number)?.toDouble() ?: return false
+                val swLat = (that["sw_lat"] as? Number)?.toDouble() ?: return false
+                val swLng = (that["sw_lng"] as? Number)?.toDouble() ?: return false
+
+                val boundingBox =
+                    BoundingBox(
+                        northeast = LocationCoordinate(neLat, neLng),
+                        southwest = LocationCoordinate(swLat, swLng),
+                    )
+                this in boundingBox
+            }
+
+            else -> false
+        }
+    }
 }