add support for direction annotations (#417)

Author: Cameron Mace

Makefile

@@ -92,6 +92,10 @@ directions-fixtures:
 	curl "https://api.mapbox.com/directions/v5/mapbox/driving/-122.416667,37.783333;-121.900000,37.333333?geometries=polyline&steps=true&access_token=$(MAPBOX_ACCESS_TOKEN)" \
 		-o mapbox/libjava-services/src/test/fixtures/directions_v5.json
 
+	# Directions: request annotations
+	curl "https://api.mapbox.com/directions/v5/mapbox/driving/-122.416667,37.783333;-121.900000,37.333333?geometries=polyline&steps=true&annotations=distance,duration,speed&access_token=$(MAPBOX_ACCESS_TOKEN)" \
+		-o mapbox/libjava-services/src/test/fixtures/directions_annotations_v5.json
+
 	# Directions: polyline geometry with precision 6
 	curl "https://api.mapbox.com/directions/v5/mapbox/driving/-122.416667,37.783333;-121.900000,37.333333?geometries=polyline6&steps=true&access_token=$(MAPBOX_ACCESS_TOKEN)" \
 		-o mapbox/libjava-services/src/test/fixtures/directions_v5_precision_6.json

mapbox/app/src/main/java/com/mapbox/services/android/testapp/directions/DirectionsV5Activity.java

@@ -108,6 +108,7 @@ private void getRoute(Position origin, Position destination) {
       .setSteps(true)
       .setOverview(DirectionsCriteria.OVERVIEW_FULL)
       .setBearings(new double[] {60, 45}, new double[] {45, 45})
+      .setAnnotation(DirectionsCriteria.ANNOTATION_DISTANCE, DirectionsCriteria.ANNOTATION_DURATION)
       .build();
 
     MapboxDirectionsRx clientRx = new MapboxDirectionsRx.Builder()
@@ -132,6 +133,7 @@ public void accept(DirectionsResponse response) throws Exception {
     client.enqueueCall(new Callback<DirectionsResponse>() {
       @Override
       public void onResponse(Call<DirectionsResponse> call, Response<DirectionsResponse> response) {
+        Log.d(LOG_TAG, "API call URL: " + call.request().url().toString());
 
         // You can get generic HTTP info about the response
         Log.d(LOG_TAG, "Response code: " + response.code());

mapbox/libjava-services-rx/src/main/java/com/mapbox/services/api/rx/directions/v5/DirectionsServiceRx.java

@@ -32,6 +32,9 @@ public interface DirectionsServiceRx {
    *                         the angle of approach
    * @param continueStraight Define whether the route should continue straight even if the route
    *                         will be slower.
+   * @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.
    * @return A retrofit Observable object
    * @since 2.0.0
    */
@@ -48,6 +51,7 @@ Observable<DirectionsResponse> getObservable(
     @Query("radiuses") String radiuses,
     @Query("steps") Boolean steps,
     @Query("bearings") String bearings,
-    @Query("continue_straight") Boolean continueStraight
+    @Query("continue_straight") Boolean continueStraight,
+    @Query("annotations") String annotations
   );
 }

mapbox/libjava-services-rx/src/main/java/com/mapbox/services/api/rx/directions/v5/MapboxDirectionsRx.java

@@ -64,7 +64,8 @@ public Observable<DirectionsResponse> getObservable() {
       builder.getRadiuses(),
       builder.isSteps(),
       builder.getBearings(),
-      builder.isContinueStraight());
+      builder.isContinueStraight(),
+      builder.getAnnotation());
 
     // Done
     return observable;

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

@@ -83,6 +83,27 @@ public class DirectionsCriteria {
    */
   public static final String OVERVIEW_FALSE = "false";
 
+  /**
+   * The duration, in seconds, between each pair of coordinates.
+   *
+   * @since 2.1.0
+   */
+  public static final String ANNOTATION_DURATION = "duration";
+
+  /**
+   * The distance, in meters, between each pair of coordinates.
+   *
+   * @since 2.1.0
+   */
+  public static final String ANNOTATION_DISTANCE = "distance";
+
+  /**
+   * The speed, in km/h, between each pair of coordinates.
+   *
+   * @since 2.1.0
+   */
+  public static final String ANNOTATION_SPEED = "speed";
+
   /**
    * Server responds with no errors.
    *

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

@@ -32,6 +32,9 @@ public interface DirectionsService {
    *                         the angle of approach
    * @param continueStraight Define whether the route should continue straight even if the route
    *                         will be slower.  @return A retrofit Call object
+   * @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.
    * @since 1.0.0
    */
   @GET("directions/v5/{user}/{profile}/{coordinates}")
@@ -48,6 +51,7 @@ Call<DirectionsResponse> getCall(
     @Query("radiuses") String radiuses,
     @Query("steps") Boolean steps,
     @Query("bearings") String bearings,
-    @Query("continue_straight") Boolean continueStraight
+    @Query("continue_straight") Boolean continueStraight,
+    @Query("annotations") String annotations
   );
 }

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

@@ -74,7 +74,8 @@ private Call<DirectionsResponse> getCall() {
       builder.getRadiuses(),
       builder.isSteps(),
       builder.getBearings(),
-      builder.isContinueStraight());
+      builder.isContinueStraight(),
+      builder.getAnnotation());
 
     // Done
     return call;
@@ -145,6 +146,7 @@ public static class Builder<T extends Builder> extends MapboxBuilder {
     private Boolean continueStraight = null;
     private Position origin = null;
     private Position destination = null;
+    private String[] annotation = null;
 
     /**
      * Constructor
@@ -340,6 +342,22 @@ public T setContinueStraight(Boolean continueStraight) {
       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 annotation can be used by separating them with {@code ,}.
+     *
+     * @param annotation String referencing one of the annotation direction criteria's.
+     * @return Builder
+     * @see <a href="https://www.mapbox.com/api-documentation/#routeleg-object">RouteLeg object documentation</a> for
+     * more information.
+     * @since 2.1.0
+     */
+    public T setAnnotation(String... annotation) {
+      this.annotation = annotation;
+      return (T) this;
+    }
+
     /*
      * Getters, they return the value in a format ready for the API to consume
      */
@@ -506,6 +524,20 @@ public Boolean isContinueStraight() {
       return continueStraight;
     }
 
+    /**
+     * returns one or a combination of {@link DirectionsCriteria#ANNOTATION_DISTANCE},
+     * {@link DirectionsCriteria#ANNOTATION_DURATION}, or {@link DirectionsCriteria#ANNOTATION_SPEED}.
+     *
+     * @return String with 1 or several annotations that have been set.
+     * @since 2.1.0
+     */
+    public String getAnnotation() {
+      if (annotation == null || annotation.length == 0) {
+        return null;
+      }
+      return TextUtils.join(",", annotation);
+    }
+
     public T setClientAppName(String appName) {
       super.clientAppName = appName;
       return (T) this;
@@ -576,6 +608,24 @@ public MapboxDirections build() throws ServicesException {
         throw new ServicesException(
           "There must be as many bearings as there are coordinates.");
       }
+
+      if (annotation != null) {
+        if (annotation.length > 3) {
+          throw new ServicesException(
+            "Annotation request can only contain one of the three DirectionsCriteria constants.");
+        }
+
+        // Check that user isn't using incorrect annotation request.
+        for (String annotationEntry : annotation) {
+          if (!annotationEntry.equals(DirectionsCriteria.ANNOTATION_DISTANCE)
+            && !annotationEntry.equals(DirectionsCriteria.ANNOTATION_DURATION)
+            && !annotationEntry.equals(DirectionsCriteria.ANNOTATION_SPEED)) {
+            throw new ServicesException(
+              "Annotation value must be one of the constant values found inside DirectionsCriteria");
+          }
+        }
+      }
+
       return new MapboxDirections(this);
     }
   }

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

@@ -2,6 +2,8 @@
 
 /**
  * Object representing lanes in an intersection.
+ *
+ * @since 2.0.0
  */
 public class IntersectionLanes {
 

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

@@ -0,0 +1,47 @@
+package com.mapbox.services.api.directions.v5.models;
+
+/**
+ * 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.
+ *
+ * @since 2.1.0
+ */
+public class LegAnnotation {
+
+  private double[] distance;
+  private double[] duration;
+  private double[] speed;
+
+  public LegAnnotation() {
+  }
+
+  /**
+   * The distance, in meters, between each pair of coordinates.
+   *
+   * @return a double array with each entry being a distance value between two of the routeLeg geometry coordinates.
+   * @since 2.1.0
+   */
+  public double[] getDistance() {
+    return distance;
+  }
+
+  /**
+   * The duration, in seconds, between each pair of coordinates.
+   *
+   * @return a double array with each entry being a duration value between two of the routeLeg geometry coordinates.
+   * @since 2.1.0
+   */
+  public double[] getDuration() {
+    return duration;
+  }
+
+  /**
+   * The speed, in km/h, between each pair of coordinates.
+   *
+   * @return a double array with each entry being a speed value between two of the routeLeg geometry coordinates.
+   * @since 2.1.0
+   */
+  public double[] getSpeed() {
+    return speed;
+  }
+}

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

@@ -13,6 +13,7 @@ public class RouteLeg {
   private double duration;
   private String summary;
   private List<LegStep> steps;
+  private LegAnnotation annotation;
 
   public RouteLeg() {
   }
@@ -56,4 +57,15 @@ public String getSummary() {
   public List<LegStep> getSteps() {
     return steps;
   }
+
+  /**
+   * An annotations object that contains additional details about each line segment along the route geometry. If you'd l
+   * ike to receiving this, you must request it inside your Directions request before executing the call.
+   *
+   * @return An {@link LegAnnotation} object.
+   * @since 2.1.0
+   */
+  public LegAnnotation getAnnotation() {
+    return annotation;
+  }
 }