Voice unit parameter for Map Matching API (#10510) (#10540)

GitOrigin-RevId: d72beb2c35cf40dbdb2e4f7f57251d92d50d5c97

Author: VysotskiVadim

changelog/unreleased/features/10510.md

@@ -0,0 +1 @@
+- Added `MapMatchingOptions.voiceUnits` which allows applications to specify the unit system used for voice instructions in Map Matching.

navigation/src/main/java/com/mapbox/navigation/core/mapmatching/MapMatchingExtras.kt

@@ -62,6 +62,21 @@ object MapMatchingExtras {
      * 	Based on TomTom OpenLR location references.
      */
     const val OPENLR_FORMAT_TOMTOM = "tomtom"
+
+    /**
+     * Voice units: imperial (default)
+     */
+    const val VOICE_UNITS_IMPERIAL = "imperial"
+
+    /**
+     * Voice units: british imperial
+     */
+    const val VOICE_UNITS_BRITISH_IMPERIAL = "british_imperial"
+
+    /**
+     * Voice units: metric
+     */
+    const val VOICE_UNITS_METRIC = "metric"
 }
 
 /**
@@ -110,3 +125,15 @@ annotation class MapMatchingOpenLRSpec
     MapMatchingExtras.OPENLR_FORMAT_TOMTOM,
 )
 annotation class MapMatchingOpenLRFormat
+
+/**
+ * Supported voice units.
+ * @see [MapMatchingOptions.Builder.voiceUnits]
+ */
+@Retention(AnnotationRetention.BINARY)
+@StringDef(
+    MapMatchingExtras.VOICE_UNITS_IMPERIAL,
+    MapMatchingExtras.VOICE_UNITS_BRITISH_IMPERIAL,
+    MapMatchingExtras.VOICE_UNITS_METRIC,
+)
+annotation class MapMatchingVoiceUnits

navigation/src/main/java/com/mapbox/navigation/core/mapmatching/MapMatchingOptions.kt

@@ -32,6 +32,7 @@ import java.net.URLEncoder
  * @param ignore defines defines certain routing restrictions to ignore when map matching.
  * @param openlrSpec defines the logical format for OpenLR encoded [coordinates].
  * @param openlrFormat defines binary format for OpenLR encoded coordinates.
+ * @param voiceUnits defines units for voice instructions.
  */
 @ExperimentalPreviewMapboxNavigationAPI
 class MapMatchingOptions private constructor(
@@ -54,6 +55,8 @@ class MapMatchingOptions private constructor(
     val ignore: List<String>?,
     val openlrSpec: String?,
     val openlrFormat: String?,
+    @MapMatchingVoiceUnits
+    val voiceUnits: String?,
 ) {
     /**
      * Compares if options are the same
@@ -81,6 +84,7 @@ class MapMatchingOptions private constructor(
         if (ignore != other.ignore) return false
         if (openlrSpec != other.openlrSpec) return false
         if (openlrFormat != other.openlrFormat) return false
+        if (voiceUnits != other.voiceUnits) return false
 
         return true
     }
@@ -106,6 +110,7 @@ class MapMatchingOptions private constructor(
         result = 31 * result + (ignore?.hashCode() ?: 0)
         result = 31 * result + (openlrSpec?.hashCode() ?: 0)
         result = 31 * result + (openlrFormat?.hashCode() ?: 0)
+        result = 31 * result + (voiceUnits?.hashCode() ?: 0)
         return result
     }
 
@@ -130,7 +135,8 @@ class MapMatchingOptions private constructor(
             "waypointNames=$waypointNames, " +
             "ignore=$ignore, " +
             "openlrSpec=$openlrSpec, " +
-            "openlrFormat=$openlrFormat" +
+            "openlrFormat=$openlrFormat, " +
+            "voiceUnits=$voiceUnits" +
             ")"
     }
 
@@ -155,6 +161,7 @@ class MapMatchingOptions private constructor(
         private var ignore: List<String>? = null
         private var openlrSpec: String? = null
         private var openlrFormat: String? = null
+        private var voiceUnits: String? = null
 
         /**
          * Required parameter.
@@ -352,6 +359,17 @@ class MapMatchingOptions private constructor(
             return this
         }
 
+        /**
+         * Optional parameter.
+         * @param voiceUnits defines units for voice instructions.
+         * Must be used with [voiceInstructions] set to true.
+         * @return this [Builder]
+         */
+        fun voiceUnits(@MapMatchingVoiceUnits voiceUnits: String?): Builder {
+            this.voiceUnits = voiceUnits
+            return this
+        }
+
         /**
          * Builds [MapMatchingOptions] based on provided values.
          */
@@ -378,6 +396,7 @@ class MapMatchingOptions private constructor(
                 ignore = ignore,
                 openlrSpec = openlrSpec,
                 openlrFormat = openlrFormat,
+                voiceUnits = voiceUnits,
             )
         }
 
@@ -408,6 +427,7 @@ class MapMatchingOptions private constructor(
             openlrSpec.toParam("openlr_spec"),
             openlrFormat.toParam("openlr_format"),
             tidy.toParam("tidy"),
+            voiceUnits.toParam("voice_units"),
         )
             .joinToString(
                 prefix = prefix,

navigation/src/test/java/com/mapbox/navigation/core/mapmatching/MapMatchingOptionsTest.kt

@@ -115,6 +115,9 @@ class MapMatchingOptionsTest {
         assertNull(
             httpUrl.queryParameter("openlr_format"),
         )
+        assertNull(
+            httpUrl.queryParameter("voice_units"),
+        )
     }
 
     @Test
@@ -383,6 +386,22 @@ class MapMatchingOptionsTest {
         )
     }
 
+    @Test
+    fun `voice units metric`() {
+        val options = createOptionsBuilderWithRequiredParams()
+            .voiceInstructions(true)
+            .voiceUnits(MapMatchingExtras.VOICE_UNITS_METRIC)
+            .build()
+
+        val url = options.toURL("***")
+
+        val httpUrl = url.toHttpUrl()
+        assertEquals(
+            "metric",
+            httpUrl.queryParameter("voice_units"),
+        )
+    }
+
     @Test
     fun `waypoints names`() {
         val options = createOptionsBuilderWithRequiredParams()