SDK changes for searchgeofences (#350)

* updated model * change search geofence interface * make radius optional * add include geometry * add in default value * change java docs * updates to java docs * update migration docs * fix copy pasta * change docs wording * bump minor version
radarlabs · Apr 30, 2024 · 99c3d2e · 99c3d2e
1 parent f44711a
commit 99c3d2e
Show file tree

Hide file tree

Showing 6 changed files with 56 additions and 26 deletions.
diff --git a/MIGRATION.md b/MIGRATION.md
@@ -1,5 +1,8 @@
 # Migration guides
 
+## 3.9.x to 3.10.x
+- The `fun searchGeofences( radius: Int, tags: Array<String>?, metadata: JSONObject?, limit: Int?, callback: RadarSearchGeofencesCallback)` method is now `fun searchGeofences( radius: Int?, tags: Array<String>?, metadata: JSONObject?, limit: Int?, includeGeometry, Boolean?, callback: RadarSearchGeofencesCallback)`  and `fun searchGeofences( near:Location, radius: Int, tags: Array<String>?, metadata: JSONObject?, limit: Int?, callback: RadarSearchGeofencesCallback)` is now `fun searchGeofences( near:Location, radius: Int?, tags: Array<String>?, metadata: JSONObject?, limit: Int?, includeGeometry, Boolean?, callback: RadarSearchGeofencesCallback)`. `radius` is now optional and `includeGeometry` needs to be set if you wish your returned geofence objects to include the full geometry of polygon geofences.
+
 ## 3.8.x to 3.9.0
 - The `Radar.autocomplete(query, near, layers, limit, country, expandUnits, callback)` method is now `Radar.autocomplete(query, near, layers, limit, country, expandUnits, mailable, callback)`.
   - `expandUnits` has been deprecated and will always be true regardless of value passed in.

diff --git a/sdk/build.gradle b/sdk/build.gradle
@@ -10,7 +10,7 @@ apply plugin: "org.jetbrains.dokka"
 apply plugin: 'io.radar.mvnpublish'
 
 ext {
-    radarVersion = '3.9.8'
+    radarVersion = '3.10.0'
 }
 
 String buildNumber = ".${System.currentTimeMillis()}"

diff --git a/sdk/src/main/java/io/radar/sdk/Radar.kt b/sdk/src/main/java/io/radar/sdk/Radar.kt
@@ -1954,18 +1954,20 @@ object Radar {
      *
      * @see [](https://radar.com/documentation/api#search-geofences)
      *
-     * @param[radius] The radius to search, in meters. A number between 100 and 10000.
+     * @param[radius] The optional radius to search, in meters. A number between 100 and 10000. If `null`, the server defaults to searching without a radius limit.
      * @param[tags] An array of tags to filter. See [](https://radar.com/documentation/geofences)
      * @param[metadata] A dictionary of metadata to filter. See [](https://radar.com/documentation/geofences)
-     * @param[limit] The max number of places to return. A number between 1 and 100.
+     * @param[limit] The max number of places to return. A number between 1 and 1000. Defaults to 100.
+     * @param[includeGeometry] Include geofence geometries in the response. Recommended to be set to false unless you specifically need the geometries. To retrieve more than 100 results, `includeGeometry` must be set to `false`.
      * @param[callback] A callback.
      */
     @JvmStatic
     fun searchGeofences(
-        radius: Int,
+        radius: Int?,
         tags: Array<String>?,
         metadata: JSONObject?,
         limit: Int?,
+        includeGeometry: Boolean? = false,
         callback: RadarSearchGeofencesCallback
     ) {
         if (!initialized) {
@@ -1985,7 +1987,7 @@ object Radar {
                     return
                 }
 
-                apiClient.searchGeofences(location, radius, tags, metadata, limit, object : RadarApiClient.RadarSearchGeofencesApiCallback {
+                apiClient.searchGeofences(location, radius, tags, metadata, limit, includeGeometry, object : RadarApiClient.RadarSearchGeofencesApiCallback {
                     override fun onComplete(status: RadarStatus, res: JSONObject?, geofences: Array<RadarGeofence>?) {
                         handler.post {
                             callback.onComplete(status, location, geofences)
@@ -2001,24 +2003,27 @@ object Radar {
      *
      * @see [](https://radar.com/documentation/api#search-geofences)
      *
-     * @param[radius] The radius to search, in meters. A number between 100 and 10000.
+     * @param[radius] The optional radius to search, in meters. A number between 100 and 10000. If `null`, the server defaults to searching without a radius limit.
      * @param[tags] An array of tags to filter. See [](https://radar.com/documentation/geofences)
      * @param[metadata] A dictionary of metadata to filter. See [](https://radar.com/documentation/geofences)
-     * @param[limit] The max number of places to return. A number between 1 and 100.
+     * @param[limit] The max number of places to return. A number between 1 and 1000. Defaults to 100.
+     * @param[includeGeometry] Include geofence geometries in the response. Recommended to be set to false unless you specifically need the geometries. To retrieve more than 100 results, `includeGeometry` must be set to `false`.
      * @param[block] A block callback.
      */
     fun searchGeofences(
-        radius: Int,
+        radius: Int?,
         tags: Array<String>?,
         metadata: JSONObject?,
         limit: Int?,
+        includeGeometry: Boolean? = false,
         block: (status: RadarStatus, location: Location?, geofences: Array<RadarGeofence>?) -> Unit
     ) {
         searchGeofences(
             radius,
             tags,
             metadata,
             limit,
+            includeGeometry,
             object : RadarSearchGeofencesCallback {
                 override fun onComplete(status: RadarStatus, location: Location?, geofences: Array<RadarGeofence>?) {
                     block(status, location, geofences)
@@ -2033,19 +2038,21 @@ object Radar {
      * @see [](https://radar.com/documentation/api#search-geofences)
      *
      * @param[near] The location to search.
-     * @param[radius] The radius to search, in meters. A number between 100 and 10000.
+     * @param[radius] The optional radius to search, in meters. A number between 100 and 10000. If `null`, the server defaults to searching without a radius limit.
      * @param[tags] An array of tags to filter. See [](https://radar.com/documentation/geofences)
      * @param[metadata] A dictionary of metadata to filter. See [](https://radar.com/documentation/geofences)
-     * @param[limit] The max number of places to return. A number between 1 and 100.
+     * @param[limit] The max number of places to return. A number between 1 and 1000. Defaults to 100.
+     * @param[includeGeometry] Include geofence geometries in the response. Recommended to be set to false unless you specifically need the geometries. To retrieve more than 100 results, `includeGeometry` must be set to `false`.
      * @param[callback] A callback.
      */
     @JvmStatic
     fun searchGeofences(
         near: Location,
-        radius: Int,
+        radius: Int?,
         tags: Array<String>?,
         metadata: JSONObject?,
         limit: Int?,
+        includeGeometry: Boolean? = false,
         callback: RadarSearchGeofencesCallback
     ) {
         if (!initialized) {
@@ -2055,7 +2062,7 @@ object Radar {
         }
         this.logger.i("searchGeofences()", RadarLogType.SDK_CALL)
 
-        apiClient.searchGeofences(near, radius, tags, metadata, limit, object : RadarApiClient.RadarSearchGeofencesApiCallback {
+        apiClient.searchGeofences(near, radius, tags, metadata, limit, includeGeometry, object : RadarApiClient.RadarSearchGeofencesApiCallback {
             override fun onComplete(status: RadarStatus, res: JSONObject?, geofences: Array<RadarGeofence>?) {
                 handler.post {
                     callback.onComplete(status, near, geofences)
@@ -2070,18 +2077,20 @@ object Radar {
      * @see [](https://radar.com/documentation/api#search-geofences)
      *
      * @param[near] The location to search.
-     * @param[radius] The radius to search, in meters. A number between 100 and 10000.
+     * @param[radius] The optional radius to search, in meters. A number between 100 and 10000. If `null`, the server defaults to searching without a radius limit.
      * @param[tags] An array of tags to filter. See [](https://radar.com/documentation/geofences)
      * @param[metadata] A dictionary of metadata to filter. See [](https://radar.com/documentation/geofences)
-     * @param[limit] The max number of places to return. A number between 1 and 100.
+     * @param[limit] The max number of places to return. A number between 1 and 1000. Defaults to 100.
+     * @param[includeGeometry] Include geofence geometries in the response. Recommended to be set to false unless you specifically need the geometries. To retrieve more than 100 results, `includeGeometry` must be set to `false`.
      * @param[block] A block callback.
      */
     fun searchGeofences(
         near: Location,
-        radius: Int,
+        radius: Int?,
         tags: Array<String>?,
         metadata: JSONObject?,
         limit: Int?,
+        includeGeometry: Boolean? = false,
         block: (status: RadarStatus, location: Location?, geofences: Array<RadarGeofence>?) -> Unit
     ) {
         searchGeofences(
@@ -2090,6 +2099,7 @@ object Radar {
             tags,
             metadata,
             limit,
+            includeGeometry,
             object : RadarSearchGeofencesCallback {
                 override fun onComplete(status: RadarStatus, location: Location?, geofences: Array<RadarGeofence>?) {
                     block(status, location, geofences)

diff --git a/sdk/src/main/java/io/radar/sdk/RadarApiClient.kt b/sdk/src/main/java/io/radar/sdk/RadarApiClient.kt
@@ -720,10 +720,11 @@ internal class RadarApiClient(
 
     internal fun searchGeofences(
         location: Location,
-        radius: Int,
+        radius: Int?,
         tags: Array<String>?,
         metadata: JSONObject?,
         limit: Int?,
+        includeGeometry: Boolean?,
         callback: RadarSearchGeofencesApiCallback
     ) {
         val publishableKey = RadarSettings.getPublishableKey(context)
@@ -735,7 +736,9 @@ internal class RadarApiClient(
 
         val queryParams = StringBuilder()
         queryParams.append("near=${location.latitude},${location.longitude}")
-        queryParams.append("&radius=${radius}")
+        if (radius != null) {
+            queryParams.append("&radius=${radius}")
+        }
         queryParams.append("&limit=${limit}")
         if (tags?.isNotEmpty() == true) {
             queryParams.append("&tags=${tags.joinToString(separator = ",")}")
@@ -745,6 +748,10 @@ internal class RadarApiClient(
             queryParams.append("&metadata[${key}]=${value}")
         }
 
+        if (includeGeometry != null) {
+            queryParams.append("&includeGeometry=${includeGeometry}")
+        }
+
         val path = "v1/search/geofences?${queryParams}"
         val headers = headers(publishableKey)
 

diff --git a/sdk/src/main/java/io/radar/sdk/model/RadarGeofence.kt b/sdk/src/main/java/io/radar/sdk/model/RadarGeofence.kt
@@ -88,9 +88,10 @@ class RadarGeofence(
                     )
                 }
                 TYPE_POLYGON, TYPE_ISOCHRONE -> {
-                    val geometryObj = obj.optJSONObject(FIELD_GEOMETRY)
-                    val coordinatesArr = geometryObj?.optJSONArray(FIELD_COORDINATES)
-                    coordinatesArr?.optJSONArray(0)?.let { coordinates ->
+                val geometryObj = obj.optJSONObject(FIELD_GEOMETRY)
+                val coordinatesArr = geometryObj?.optJSONArray(FIELD_COORDINATES)
+                if (coordinatesArr != null) {
+                    coordinatesArr.optJSONArray(0)?.let { coordinates ->
                         val polygonCoordinatesArr = Array(coordinates.length()) { index ->
                             coordinates.optJSONArray(index)?.let { coordinate ->
                                 RadarCoordinate(
@@ -105,6 +106,13 @@ class RadarGeofence(
                             radius
                         )
                     }
+                } else {
+                    RadarPolygonGeometry(
+                        null,
+                        center,
+                        radius
+                    )
+                }
                 }
                 else -> null
             } ?: RadarCircleGeometry(RadarCoordinate(0.0, 0.0), 0.0)
@@ -170,11 +178,13 @@ class RadarGeofence(
                 is RadarPolygonGeometry -> {
                     obj.putOpt(FIELD_GEOMETRY_CENTER, geometry.center.toJson())
                     obj.putOpt(FIELD_GEOMETRY_RADIUS, geometry.radius)
-                    /* Nest coordinate array; Per GeoJSON spec: for type "Polygon", the
-                     "coordinates" member must be an array of LinearRing coordinate arrays. */
-                    val geometryCoordinates = JSONArray()
-                    geometryCoordinates.put(toJson(geometry.coordinates))
-                    obj.putOpt(FIELD_COORDINATES, geometryCoordinates)
+                    if (geometry.coordinates != null) {
+                        /* Nest coordinate array; Per GeoJSON spec: for type "Polygon", the
+                        "coordinates" member must be an array of LinearRing coordinate arrays. */
+                        val geometryCoordinates = JSONArray()
+                        geometryCoordinates.put(toJson(geometry.coordinates))
+                        obj.putOpt(FIELD_COORDINATES, geometryCoordinates)
+                    }
                     obj.putOpt(FIELD_TYPE, TYPE_GEOMETRY_POLYGON)
                 }
             }

diff --git a/sdk/src/main/java/io/radar/sdk/model/RadarGeofenceGeometry.kt b/sdk/src/main/java/io/radar/sdk/model/RadarGeofenceGeometry.kt
@@ -27,7 +27,7 @@ class RadarPolygonGeometry(
     /**
      * The geometry of the polygon geofence. A closed ring of coordinates.
      */
-    val coordinates: Array<RadarCoordinate>,
+    val coordinates: Array<RadarCoordinate>? = null,
 
     /**
      * The calculated centroid of the polygon geofence.