Updated optimization API (#506)

* updated optimization API

* deprecated misspelled method

* fixed up optimization waypoint object

Author: Cameron Mace

Makefile

@@ -120,3 +120,9 @@ optimized-trips-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)" \
 		-o mapbox/libjava-services/src/test/fixtures/optimized_trip.json
+
+	curl "https://api.mapbox.com/optimized-trips/v1/mapbox/cycling/-122.42,37.78;-122.45,37.91;-122.48,37.73?steps=true&language=sv&access_token=$(MAPBOX_ACCESS_TOKEN)" \
+		-o mapbox/libjava-services/src/test/fixtures/optimized_trip_steps.json
+
+	curl "https://api.mapbox.com/optimized-trips/v1/mapbox/driving/13.388860,52.517037;13.397634,52.529407;13.428555,52.523219;13.418555,52.523215?roundtrip=true&distributions=3,1&access_token=$(MAPBOX_ACCESS_TOKEN)" \
+		-o mapbox/libjava-services/src/test/fixtures/optimized_trip_distributions.json

mapbox/libjava-services-rx/src/main/java/com/mapbox/services/api/rx/optimizedtrips/v1/MapboxOptimizedTripsRx.java

@@ -72,7 +72,9 @@ public Observable<OptimizedTripsResponse> getObservable() {
       builder.getGeometries(),
       builder.getAnnotation(),
       builder.getDestination(),
-      builder.getSource());
+      builder.getSource(),
+      builder.getLanguage(),
+      builder.getDistributions());
 
     // Done
     return observable;

mapbox/libjava-services-rx/src/main/java/com/mapbox/services/api/rx/optimizedtrips/v1/OptimizedTripsServiceRx.java

@@ -16,26 +16,28 @@
 public interface OptimizedTripsServiceRx {
 
   /**
-   * @param userAgent   The user.
-   * @param user        The user.
-   * @param profile     The profile directions should use.
-   * @param coordinates The coordinates used to calculate the trip.
-   * @param accessToken Mapbox access token.
-   * @param roundTrip   Returned route is a roundtrip (route returns to first location). Allowed values are: true
-   *                    (default) or false.
-   * @param radiuses    Maximum distance in meters that each coordinate is allowed to move when snapped to a nearby
-   *                    road segment. There must be as many radiuses as there are coordinates in the request. Values
-   *                    can be any number greater than 0 or they can be the string unlimited. If no routable road is
-   *                    found within the radius, a NoSegment error is returned.
-   * @param bearings    Used to filter the road segment the waypoint will be placed on by direction and dictates
-   *                    the angle of approach
-   * @param steps       Define if you'd like the route steps.
-   * @param geometries  Route geometry.
-   * @param annotations An annotations object that contains additional details about each line segment along the
-   *                    route geometry. Each entry in an annotations field corresponds to a coordinate along the
-   *                    route geometry.
-   * @param destination Returned route ends at any or last coordinate. Allowed values are: any (default) or last.
-   * @param source      Returned route starts at any or first coordinate. Allowed values are: any (default) or first.
+   * @param userAgent     The user.
+   * @param user          The user.
+   * @param profile       The profile directions should use.
+   * @param coordinates   The coordinates used to calculate the trip.
+   * @param accessToken   Mapbox access token.
+   * @param roundTrip     Returned route is a roundtrip (route returns to first location). Allowed values are: true
+   *                      (default) or false.
+   * @param radiuses      Maximum distance in meters that each coordinate is allowed to move when snapped to a nearby
+   *                      road segment. There must be as many radiuses as there are coordinates in the request. Values
+   *                      can be any number greater than 0 or they can be the string unlimited. If no routable road is
+   *                      found within the radius, a NoSegment error is returned.
+   * @param bearings      Used to filter the road segment the waypoint will be placed on by direction and dictates
+   *                      the angle of approach
+   * @param steps         Define if you'd like the route steps.
+   * @param geometries    Route geometry.
+   * @param annotations   An annotations object that contains additional details about each line segment along the
+   *                      route geometry. Each entry in an annotations field corresponds to a coordinate along the
+   *                      route geometry.
+   * @param destination   Returned route ends at any or last coordinate. Allowed values are: any (default) or last.
+   * @param source        Returned route starts at any or first coordinate. Allowed values are: any (default) or first.
+   * @param language      Language of returned turn-by-turn text instructions.
+   * @param distributions Specify pick-up and drop-off locations
    * @since 2.1.0
    */
   @GET("optimized-trips/v1/{user}/{profile}/{coordinates}")
@@ -46,13 +48,15 @@ Observable<OptimizedTripsResponse> getObservable(
     @Path("coordinates") String coordinates,
     @Query("access_token") String accessToken,
     @Query("roundtrip") Boolean roundTrip,
-    @Query("radiuses") double[] radiuses,
-    @Query("bearings") double[][] bearings,
+    @Query("radiuses") String radiuses,
+    @Query("bearings") String bearings,
     @Query("steps") Boolean steps,
     @Query("overview") String overview,
     @Query("geometries") String geometries,
     @Query("annotations") String[] annotations,
     @Query("destination") String destination,
-    @Query("source") String source
+    @Query("source") String source,
+    @Query("language") String language,
+    @Query("distributions") String distributions
   );
 }

mapbox/libjava-services/src/main/java/com/mapbox/services/api/directions/v5/models/DirectionsWaypoint.java

@@ -41,7 +41,7 @@ public void setName(String name) {
   }
 
   /**
-   * an array with two double values reresenting the maneuver locations coordinate.
+   * an array with two double values representing the maneuver locations coordinate.
    *
    * @return double array of [longitude, latitude] for the snapped coordinate.
    * @since 1.0.0

mapbox/libjava-services/src/main/java/com/mapbox/services/api/mapmatching/v5/models/MapMatchingTracepoint.java

@@ -15,6 +15,9 @@ public class MapMatchingTracepoint extends DirectionsWaypoint {
   @SerializedName("waypoint_index")
   private int waypointIndex;
 
+  /**
+   * Public constructor
+   */
   public MapMatchingTracepoint() {
   }
 
@@ -28,6 +31,7 @@ public MapMatchingTracepoint(int matchingsIndex, int alternativesCount, int wayp
    * Index to the match object in matchings the sub-trace was matched to.
    *
    * @return index value
+   * @since 2.2.0
    */
   public int getMatchingsIndex() {
     return matchingsIndex;
@@ -37,6 +41,7 @@ public int getMatchingsIndex() {
    * Index value
    *
    * @param matchingsIndex value
+   * @since 2.2.0
    */
   public void setMatchingsIndex(int matchingsIndex) {
     this.matchingsIndex = matchingsIndex;
@@ -46,6 +51,7 @@ public void setMatchingsIndex(int matchingsIndex) {
    * Index of the waypoint inside the matched route.
    *
    * @return index value
+   * @since 2.2.0
    */
   public int getWaypointIndex() {
     return waypointIndex;

mapbox/libjava-services/src/main/java/com/mapbox/services/api/optimizedtrips/v1/MapboxOptimizedTrips.java

@@ -85,7 +85,9 @@ private Call<OptimizedTripsResponse> getCall() {
       builder.getGeometries(),
       builder.getAnnotation(),
       builder.getDestination(),
-      builder.getSource());
+      builder.getSource(),
+      builder.getLanguage(),
+      builder.getDistributions());
 
     // Done
     return call;
@@ -153,8 +155,10 @@ public static class Builder<T extends Builder> extends MapboxBuilder {
     private double[] radiuses;
     private Boolean steps;
     private double[][] bearings;
-    private String[] annotation;
+    private String[] annotations;
     private String overview;
+    private String language;
+    private double[][] distributions;
 
     /**
      * Constructor
@@ -340,15 +344,32 @@ public T setBearings(double[]... bearings) {
     /**
      * Whether or not to return additional metadata along the route. Possible values are:
      * {@link DirectionsCriteria#ANNOTATION_DISTANCE}, {@link DirectionsCriteria#ANNOTATION_DURATION}, and
-     * {@link DirectionsCriteria#ANNOTATION_SPEED}. Several annotation can be used by separating them with {@code ,}.
+     * {@link DirectionsCriteria#ANNOTATION_SPEED}. Several annotations can be used by separating them with {@code ,}.
      *
-     * @param annotation String referencing one of the annotation direction criteria's.
+     * @param annotation String referencing one of the annotations direction criteria's.
      * @return Builder
      * @see <a href="https://www.mapbox.com/api-documentation/#routeleg-object">RouteLeg object documentation</a>
      * @since 2.1.0
+     * @deprecated use {@link Builder#getAnnotations()} instead
      */
+    @Deprecated
     public T setAnnotation(String... annotation) {
-      this.annotation = annotation;
+      this.annotations = annotation;
+      return (T) this;
+    }
+
+    /**
+     * Whether or not to return additional metadata along the route. Possible values are:
+     * {@link DirectionsCriteria#ANNOTATION_DISTANCE}, {@link DirectionsCriteria#ANNOTATION_DURATION}, and
+     * {@link DirectionsCriteria#ANNOTATION_SPEED}. Several annotations can be used by separating them with {@code ,}.
+     *
+     * @param annotation String referencing one of the annotations direction criteria's.
+     * @return Builder
+     * @see <a href="https://www.mapbox.com/api-documentation/#routeleg-object">RouteLeg object documentation</a>
+     * @since 2.1.0
+     */
+    public T setAnnotations(String... annotation) {
+      this.annotations = annotation;
       return (T) this;
     }
 
@@ -376,6 +397,38 @@ public T setClientAppName(String appName) {
       return (T) this;
     }
 
+    /**
+     * Optionally set the language of returned turn-by-turn text instructions. The default is {@code en} for English.
+     *
+     * @param language The locale in which results should be returned.
+     * @return Builder
+     * @see <a href="https://www.mapbox.com/api-documentation/#instructions-languages">Supported languages</a>
+     * @since 2.2.0
+     */
+    public T setLanguage(String language) {
+      this.language = language;
+      return (T) this;
+    }
+
+    /**
+     * Specify pick-up and drop-off locations for a trip by providing a {@code double[]} each with a number pair that
+     * correspond with the coordinates list. The first number indicates what place the coordinate of the pick-up
+     * location is in the coordinates list, and the second number indicates what place the coordinate of the drop-off
+     * location is in the coordinates list. Each pair must contain exactly two numbers. Pick-up and drop-off locations
+     * in one pair cannot be the same. The returned solution will visit pick-up locations before visiting drop-off
+     * locations. The depot (first location) can only be a pick-up location but not a drop-off location.
+     *
+     * @param distributions {@code double[]} with two values, first being the pickup coordinate in the coordinates list
+     *                      and the second number being the coordinate in the coordinates list which should be the drop
+     *                      off location.
+     * @return Builder
+     * @since 2.2.0
+     */
+    public T setDistributions(double[]... distributions) {
+      this.distributions = distributions;
+      return (T) this;
+    }
+
     /*
      * Getters
      */
@@ -462,11 +515,24 @@ public String getGeometries() {
      * Get the maximum distance in meters you have set that each coordinate is allowed to move when snapped to a nearby
      * road segment.
      *
-     * @return double array containing the radiuses defined in unit meters.
+     * @return String containing the radiuses defined in unit meters.
      * @since 2.1.0
      */
-    public double[] getRadiuses() {
-      return radiuses;
+    public String getRadiuses() {
+      if (radiuses == null || radiuses.length == 0) {
+        return null;
+      }
+
+      String[] radiusesFormatted = new String[radiuses.length];
+      for (int i = 0; i < radiuses.length; i++) {
+        if (radiuses[i] == Double.POSITIVE_INFINITY) {
+          radiusesFormatted[i] = "unlimited";
+        } else {
+          radiusesFormatted[i] = String.format(Locale.US, "%s", TextUtils.formatCoordinate(radiuses[i]));
+        }
+      }
+
+      return TextUtils.join(";", radiusesFormatted);
     }
 
     /**
@@ -502,24 +568,52 @@ public Boolean getSteps() {
      * Determine whether you are filtering the road segment the waypoint will be placed on by direction and dictating
      * the angle of approach.
      *
-     * @return a double array with two values indicating the angle and the other value indicating the deviating
+     * @return String with two values indicating the angle and the other value indicating the deviating
      * range.
      * @since 2.1.0
      */
-    public double[][] getBearings() {
-      return bearings;
+    public String getBearings() {
+      if (bearings == null || bearings.length == 0) {
+        return null;
+      }
+
+      String[] bearingFormatted = new String[bearings.length];
+      for (int i = 0; i < bearings.length; i++) {
+        if (bearings[i].length == 0) {
+          bearingFormatted[i] = "";
+        } else {
+          bearingFormatted[i] = String.format(Locale.US, "%s,%s",
+            TextUtils.formatCoordinate(bearings[i][0]),
+            TextUtils.formatCoordinate(bearings[i][1]));
+        }
+      }
+      return TextUtils.join(";", bearingFormatted);
     }
 
     /**
      * Determine whether or not you are currently requesting additional metadata along the route. Possible values are:
      * {@link DirectionsCriteria#ANNOTATION_DISTANCE}, {@link DirectionsCriteria#ANNOTATION_DURATION}, and
-     * {@link DirectionsCriteria#ANNOTATION_SPEED}. Several annotation can be used by separating them with {@code ,}.
+     * {@link DirectionsCriteria#ANNOTATION_SPEED}. Several annotations can be used by separating them with {@code ,}.
      *
-     * @return String referencing one of the annotation direction criteria's.
+     * @return String referencing one of the annotations direction criteria's.
      * @since 2.1.0
+     * @deprecated Use {@link Builder#getAnnotations()}
      */
+    @Deprecated
     public String[] getAnnotation() {
-      return annotation;
+      return annotations;
+    }
+
+    /**
+     * Determine whether or not you are currently requesting additional metadata along the route. Possible values are:
+     * {@link DirectionsCriteria#ANNOTATION_DISTANCE}, {@link DirectionsCriteria#ANNOTATION_DURATION}, and
+     * {@link DirectionsCriteria#ANNOTATION_SPEED}. Several annotations can be used by separating them with {@code ,}.
+     *
+     * @return String referencing one of the annotations direction criteria's.
+     * @since 2.1.0
+     */
+    public String[] getAnnotations() {
+      return annotations;
     }
 
     /**
@@ -531,6 +625,38 @@ public String getAccessToken() {
       return accessToken;
     }
 
+    /**
+     * @return The language the turn-by-turn directions will be in.
+     * @since 2.2.0
+     */
+    public String getLanguage() {
+      return language;
+    }
+
+    /**
+     * If distribution values are set inside your request, this will return a String containing the given values.
+     *
+     * @return String containing the provided distribution values.
+     * @since 2.2.0
+     */
+    public String getDistributions() {
+      if (distributions == null || distributions.length == 0) {
+        return null;
+      }
+
+      String[] distributionsFormatted = new String[distributions.length];
+      for (int i = 0; i < distributions.length; i++) {
+        if (distributions[i].length == 0) {
+          distributionsFormatted[i] = "";
+        } else {
+          distributionsFormatted[i] = String.format(Locale.US, "%s,%s",
+            TextUtils.formatCoordinate(distributions[i][0]),
+            TextUtils.formatCoordinate(distributions[i][1]));
+        }
+      }
+      return TextUtils.join(";", distributionsFormatted);
+    }
+
     /**
      * Build method
      *