Added missing param to MapboxMapMatching Builder: (#718)

Added the following param to MapboxMapMatching Builder: 
-roundaboutExits
-bannerInstructions
-voiceInstructions
-waypoints

Author: osana

Makefile

@@ -1,3 +1,6 @@
+# Used for Map Matching
+MAP_MATCHING_COORDINATES = 13.418946862220764,52.50055852688439;13.419011235237122,52.50113000479732;13.419756889343262,52.50171780290061;13.419885635375975,52.50237416816131;13.420631289482117,52.50294888790448
+
 build-config:
 	./gradlew compileBuildConfig
 
@@ -105,6 +108,7 @@ mapmatching-fixtures:
 	curl "https://api.mapbox.com/matching/v5/mapbox/driving/$(MAP_MATCHING_COORDINATES)?geometries=polyline&language=sv&steps=true&access_token=$(MAPBOX_ACCESS_TOKEN)" \
 		-o services-matching/src/test/resources/mapmatching_v5_polyline.json
 
+
 optimization-fixtures:
 	# request an optimized car trip with no additional options
 	curl "https://api.mapbox.com/optimized-trips/v1/mapbox/driving/-122.42,37.78;-122.45,37.91;-122.48,37.73?access_token=$(MAPBOX_ACCESS_TOKEN)" \

services-matching/src/main/java/com/mapbox/api/matching/v5/MapMatchingService.java

@@ -50,6 +50,12 @@ public interface MapMatchingService {
    * @param language    language of returned turn-by-turn text instructions
    * @param tidy        whether or not to transparently remove clusters and re-sample traces for
    *                    improved map matching results
+   * @param roundaboutExits  Whether or not to emit instructions at roundabout exits.
+   * @param bannerInstructions Whether or not to return banner objects associated with the `routeSteps`.
+   *                           Should be used in conjunction with `steps`.
+   * @param voiceInstructions whether or not to return
+   *                        marked-up text for voice guidance along the route.
+   * @param waypoints  Which input coordinates should be treated as waypoints.
    * @return the MapMatchingResponse in a Call wrapper
    * @since 2.0.0
    */
@@ -67,5 +73,9 @@ Call<MapMatchingResponse> getCall(
     @Query("timestamps") String timestamps,
     @Query("annotations") String annotations,
     @Query("language") String language,
-    @Query("tidy") Boolean tidy);
+    @Query("tidy") Boolean tidy,
+    @Query("roundabout_exits") Boolean roundaboutExits,
+    @Query("banner_instructions") Boolean bannerInstructions,
+    @Query("voice_instructions") Boolean voiceInstructions,
+    @Query("waypoints") String waypoints);
 }

services-matching/src/main/java/com/mapbox/api/matching/v5/MapboxMapMatching.java

@@ -1,6 +1,7 @@
 package com.mapbox.api.matching.v5;
 
 import android.support.annotation.FloatRange;
+import android.support.annotation.IntRange;
 import android.support.annotation.NonNull;
 import android.support.annotation.Nullable;
 import com.google.auto.value.AutoValue;
@@ -97,7 +98,11 @@ public Call<MapMatchingResponse> getCall() {
       timestamps(),
       annotations(),
       language(),
-      tidy()
+      tidy(),
+      roundaboutExits(),
+      bannerInstructions(),
+      voiceInstructions(),
+      waypoints()
     );
 
     return call;
@@ -190,6 +195,19 @@ public Call<MapMatchingResponse> cloneCall() {
   @Nullable
   abstract String language();
 
+  @Nullable
+  abstract Boolean roundaboutExits();
+
+  @Nullable
+  abstract Boolean bannerInstructions();
+
+  @Nullable
+  abstract Boolean voiceInstructions();
+
+  @Nullable
+  abstract String waypoints();
+
+
   @NonNull
   abstract String baseUrl();
 
@@ -220,6 +238,7 @@ public abstract static class Builder {
     private String[] annotations;
     private String[] timestamps;
     private Double[] radiuses;
+    private Integer[] waypoints;
 
     /**
      * Required to call when this is being built. If no access token provided,
@@ -303,6 +322,28 @@ public Builder radiuses(@Nullable @FloatRange(from = 0) Double... radiuses) {
     // Required for matching with MapboxMapMatching radiuses() method.
     abstract Builder radiuses(@Nullable String radiuses);
 
+
+    /**
+     * Optionally, set which input coordinates should be treated as waypoints.
+     * <p>
+     * Most useful in combination with  steps=true and requests based on traces with high sample rates.
+     * Can be an index corresponding to any of the input coordinates,
+     * but must contain the first ( 0 ) and last coordinates' index separated by  ; .
+     * {@link #steps()}
+     * </p>
+     *
+     * @param waypoints integer array of coordinate indices to be used as waypoints
+     * @return this builder for chaining options together
+     * @since 3.0.0
+     */
+    public Builder waypoints(@Nullable @IntRange(from = 0) Integer... waypoints) {
+      this.waypoints = waypoints;
+      return this;
+    }
+
+    // Required for matching with MapboxMapMatching waypoints() method.
+    abstract Builder waypoints(@Nullable String waypoints);
+
     /**
      * Setting this will determine whether to return steps and turn-by-turn instructions. Can be
      * set to either true or false to enable or disable respectively. null can also optionally be
@@ -327,6 +368,42 @@ public Builder radiuses(@Nullable @FloatRange(from = 0) Double... radiuses) {
      */
     public abstract Builder overview(@Nullable @OverviewCriteria String overview);
 
+    /**
+     * Setting this will determine Whether or not to return banner objects associated with the `routeSteps`.
+     * Should be used in conjunction with `steps`. Can be set to either true or false to enable or
+     * disable respectively. null can also optionally be
+     * passed in to set the default behavior to match what the API does by default.
+     *
+     * @param bannerInstructions true if you'd like step information
+     * @return this builder for chaining options together
+     * @since 3.0.0
+     */
+    public abstract Builder bannerInstructions(@Nullable Boolean bannerInstructions);
+
+
+    /**
+     * Setting this will determine whether to return steps and turn-by-turn instructions. Can be
+     * set to either true or false to enable or disable respectively. null can also optionally be
+     * passed in to set the default behavior to match what the API does by default.
+     *
+     * @param voiceInstructions true if you'd like step information
+     * @return this builder for chaining options together
+     * @since 3.0.0
+     */
+    public abstract Builder voiceInstructions(@Nullable Boolean voiceInstructions);
+
+
+    /**
+     * Setting this will determine whether to return steps and turn-by-turn instructions. Can be
+     * set to either true or false to enable or disable respectively. null can also optionally be
+     * passed in to set the default behavior to match what the API does by default.
+     *
+     * @param roundaboutExits true if you'd like step information
+     * @return this builder for chaining options together
+     * @since 3.0.0
+     */
+    public abstract Builder roundaboutExits(@Nullable Boolean roundaboutExits);
+
     /**
      * Whether or not to return additional metadata along the route. Possible values are:
      * {@link DirectionsCriteria#ANNOTATION_DISTANCE},
@@ -486,10 +563,29 @@ public MapboxMapMatching build() {
           "There must be as many timestamps as there are coordinates.");
       }
 
+      if (waypoints != null) {
+        if (waypoints.length < 2) {
+          throw new ServicesException(
+            "Waypoints must be a list of at least two indexes separated by ';'");
+        }
+        if (waypoints[0] != 0 || waypoints[waypoints.length - 1] != coordinates.size() - 1) {
+          throw new ServicesException(
+            "Waypoints must contain indices of the first and last coordinates"
+          );
+        }
+        for (int i = 1; i < waypoints.length -1; i++) {
+          if (waypoints[i] < 0 || waypoints[i] >= coordinates.size()) {
+            throw new ServicesException(
+              "Waypoints index too large (no corresponding coordinate)");
+          }
+        }
+      }
+
       coordinates(formatCoordinates(coordinates));
       timestamps(TextUtils.join(",", timestamps));
       annotations(TextUtils.join(",", annotations));
       radiuses(TextUtils.join(",", radiuses));
+      waypoints(TextUtils.join(";", waypoints));
 
       // Generate build so that we can check that values are valid.
       MapboxMapMatching mapMatching = autoBuild();

services-matching/src/test/java/com/mapbox/api/matching/v5/MapboxMapMatchingTest.java

@@ -333,4 +333,120 @@ public void baseUrl_doesShowInUrlCorrectly() throws Exception {
     assertTrue(mapMatching.cloneCall().request().url().toString()
       .startsWith("https://foobar.com"));
   }
+
+
+  @Test
+  public void build_exceptionThrownWhenLessThanTwoWayPointsProvided() throws Exception {
+    thrown.expect(ServicesException.class);
+    thrown.expectMessage(
+      startsWith("Waypoints must be a list of at least two indexes separated by"));
+    MapboxMapMatching mapMatching = MapboxMapMatching.builder()
+      .coordinate(Point.fromLngLat(2.0, 2.0))
+      .coordinate(Point.fromLngLat(4.0, 4.0))
+      .waypoints(0)
+      .baseUrl("https://foobar.com")
+      .accessToken(ACCESS_TOKEN)
+      .build();
+  }
+
+  @Test
+  public void build_exceptionThrownWhenWaypointsDoNotStartWith0() throws Exception {
+    thrown.expect(ServicesException.class);
+    thrown.expectMessage(
+      startsWith("Waypoints must contain indices of the first and last coordinates"));
+    MapboxMapMatching mapMatching = MapboxMapMatching.builder()
+      .coordinate(Point.fromLngLat(2.0, 2.0))
+      .coordinate(Point.fromLngLat(3.0, 3.0))
+      .coordinate(Point.fromLngLat(4.0, 4.0))
+      .waypoints(1, 2)
+      .baseUrl("https://foobar.com")
+      .accessToken(ACCESS_TOKEN)
+      .build();
+  }
+
+  @Test
+  public void build_exceptionThrownWhenWaypointDoNotEndWithLast() throws Exception {
+    thrown.expect(ServicesException.class);
+    thrown.expectMessage(
+      startsWith("Waypoints must contain indices of the first and last coordinates"));
+    MapboxMapMatching mapMatching = MapboxMapMatching.builder()
+      .coordinate(Point.fromLngLat(2.0, 2.0))
+      .coordinate(Point.fromLngLat(3.0, 3.0))
+      .coordinate(Point.fromLngLat(4.0, 4.0))
+      .waypoints(0, 1)
+      .baseUrl("https://foobar.com")
+      .accessToken(ACCESS_TOKEN)
+      .build();
+  }
+
+  @Test
+  public void build_exceptionThrownWhenMiddleWaypointsAreWrong() throws Exception {
+    thrown.expect(ServicesException.class);
+    thrown.expectMessage(
+      startsWith("Waypoints index too large (no corresponding coordinate)"));
+    MapboxMapMatching mapMatching = MapboxMapMatching.builder()
+      .coordinate(Point.fromLngLat(2.0, 2.0))
+      .coordinate(Point.fromLngLat(3.0, 3.0))
+      .coordinate(Point.fromLngLat(4.0, 4.0))
+      .waypoints(0, 3, 2)
+      .baseUrl("https://foobar.com")
+      .accessToken(ACCESS_TOKEN)
+      .build();
+  }
+
+  @Test
+  public void sanityWaypoints() throws Exception {
+    MapboxMapMatching mapMatching = MapboxMapMatching.builder()
+      .coordinate(Point.fromLngLat(2.0, 2.0))
+      .coordinate(Point.fromLngLat(3.0, 3.0))
+      .coordinate(Point.fromLngLat(4.0, 4.0))
+      .waypoints(0, 1, 2)
+      .baseUrl("https://foobar.com")
+      .accessToken(ACCESS_TOKEN)
+      .build();
+    assertNotNull(mapMatching);
+  }
+
+  @Test
+  public void sanityVoiceInstructions() throws Exception {
+    MapboxMapMatching mapMatching = MapboxMapMatching.builder()
+      .coordinate(Point.fromLngLat(2.0, 2.0))
+      .coordinate(Point.fromLngLat(4.0, 4.0))
+      .voiceInstructions(true)
+      .baseUrl("https://foobar.com")
+      .accessToken(ACCESS_TOKEN)
+      .build();
+    assertNotNull(mapMatching);
+    assertTrue(mapMatching.cloneCall().request().url().toString()
+      .contains("voice_instructions=true"));
+  }
+
+  @Test
+  public void sanityBannerInstructions() throws Exception {
+    MapboxMapMatching mapMatching = MapboxMapMatching.builder()
+      .coordinate(Point.fromLngLat(2.0, 2.0))
+      .coordinate(Point.fromLngLat(4.0, 4.0))
+      .bannerInstructions(true)
+      .baseUrl("https://foobar.com")
+      .accessToken(ACCESS_TOKEN)
+      .build();
+    assertNotNull(mapMatching);
+    assertTrue(mapMatching.cloneCall().request().url().toString()
+      .contains("banner_instructions=true"));
+  }
+
+  @Test
+  public void sanityRoundExtsInstructions() throws Exception {
+    MapboxMapMatching mapMatching = MapboxMapMatching.builder()
+      .coordinate(Point.fromLngLat(2.0, 2.0))
+      .coordinate(Point.fromLngLat(4.0, 4.0))
+      .roundaboutExits(true)
+      .baseUrl("https://foobar.com")
+      .accessToken(ACCESS_TOKEN)
+      .build();
+    assertNotNull(mapMatching);
+    assertTrue(mapMatching.cloneCall().request().url().toString()
+      .contains("roundabout_exits=true"));
+  }
+
 }