Add MaxSpeed Annotation to Directions API (#772)

* Initial annotation work

* Finish maxspeed, add docs, adjust constant

* Update javadoc

* Update type adapter

* Add builder

* Add model tests

* Add missing maxspeed builder

* Add missing javadoc

* Adjust doc line length

Author: danesfeder

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

@@ -115,6 +115,13 @@ public final class DirectionsCriteria {
    */
   public static final String ANNOTATION_CONGESTION = "congestion";
 
+  /**
+   * The posted speed limit, between each pair of coordinates.
+   *
+   * @since 2.1.0
+   */
+  public static final String ANNOTATION_MAXSPEED = "maxspeed";
+
   /**
    * Exclude all tolls along the returned directions route.
    *
@@ -255,7 +262,8 @@ private DirectionsCriteria() {
     ANNOTATION_CONGESTION,
     ANNOTATION_DISTANCE,
     ANNOTATION_DURATION,
-    ANNOTATION_SPEED
+    ANNOTATION_SPEED,
+    ANNOTATION_MAXSPEED
   })
   public @interface AnnotationCriteria {
   }

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

@@ -58,6 +58,18 @@ public static Builder builder() {
   @Nullable
   public abstract List<Double> speed();
 
+  /**
+   * The posted speed limit, between each pair of coordinates.
+   * Maxspeed is only available for the `mapbox/driving` and `mapbox/driving-traffic`
+   * profiles, other profiles will return `unknown`s only.
+   *
+   * @return a list with each entry being a {@link MaxSpeed} value between two of
+   *   the routeLeg geometry coordinates
+   * @since 3.0.0
+   */
+  @Nullable
+  public abstract List<MaxSpeed> maxSpeed();
+
   /**
    * The congestion between each pair of coordinates.
    *
@@ -117,6 +129,17 @@ public abstract static class Builder {
      */
     public abstract Builder speed(@Nullable List<Double> speed);
 
+    /**
+     * The posted speed limit, between each pair of coordinates.
+     * Maxspeed is only available for the `mapbox/driving` and `mapbox/driving-traffic`
+     * profiles, other profiles will return `unknown`s only.
+     *
+     * @param maxSpeed list of speeds between each pair of coordinates
+     * @return this builder for chaining options together
+     * @since 3.0.0
+     */
+    public abstract Builder maxSpeed(@Nullable List<MaxSpeed> maxSpeed);
+
     /**
      * The congestion between each pair of coordinates.
      *

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

@@ -0,0 +1,124 @@
+package com.mapbox.api.directions.v5.models;
+
+import android.support.annotation.Nullable;
+
+import com.google.auto.value.AutoValue;
+import com.google.gson.Gson;
+import com.google.gson.TypeAdapter;
+
+import java.io.Serializable;
+
+/**
+ * Object representing max speeds along a route.
+ *
+ * @since 3.0.0
+ */
+@AutoValue
+public abstract class MaxSpeed implements Serializable {
+
+  /**
+   * Create a new instance of this class by using the {@link Builder} class.
+   *
+   * @return {@link Builder} for creating a new instance
+   * @since 3.0.0
+   */
+  public static Builder builder() {
+    return new AutoValue_MaxSpeed.Builder();
+  }
+
+  /**
+   * Number indicating the posted speed limit.
+   *
+   * @return number indicating the posted speed limit
+   * @since 3.0.0
+   */
+  @Nullable
+  public abstract Integer speed();
+
+  /**
+   * String indicating the unit of speed, either as `km/h` or `mph`.
+   *
+   * @return String unit either as `km/h` or `mph`
+   * @since 3.0.0
+   */
+  @Nullable
+  public abstract String unit();
+
+  /**
+   * Boolean is true if the speed limit is not known, otherwise null.
+   *
+   * @return Boolean true if speed limit is not known, otherwise null
+   * @since 3.0.0
+   */
+  @Nullable
+  public abstract Boolean unknown();
+
+  /**
+   * Boolean is `true` if the speed limit is unlimited, otherwise null.
+   *
+   * @return Boolean true if speed limit is unlimited, otherwise null
+   * @since 3.0.0
+   */
+  @Nullable
+  public abstract Boolean none();
+
+  /**
+   * Gson type adapter for parsing Gson to this class.
+   *
+   * @param gson the built {@link Gson} object
+   * @return the type adapter for this class
+   * @since 3.0.0
+   */
+  public static TypeAdapter<MaxSpeed> typeAdapter(Gson gson) {
+    return new AutoValue_MaxSpeed.GsonTypeAdapter(gson);
+  }
+
+  /**
+   * This builder can be used to set the values describing the {@link MaxSpeed}.
+   *
+   * @since 3.0.0
+   */
+  @AutoValue.Builder
+  public abstract static class Builder {
+
+    /**
+     * Number indicating the posted speed limit.
+     *
+     * @param speed indicating the posted speed limit
+     * @since 3.0.0
+     */
+    public abstract Builder speed(@Nullable Integer speed);
+
+    /**
+     * String indicating the unit of speed, either as `km/h` or `mph`.
+     *
+     * @param unit either as `km/h` or `mph`
+     * @since 3.0.0
+     */
+    public abstract Builder unit(@Nullable String unit);
+
+    /**
+     * Boolean is true if the speed limit is not known, otherwise null.
+     *
+     * @param unknown true if speed limit is not known, otherwise null
+     * @since 3.0.0
+     */
+    public abstract Builder unknown(@Nullable Boolean unknown);
+
+    /**
+     * Boolean is `true` if the speed limit is unlimited, otherwise null.
+     *
+     * @param none true if speed limit is unlimited, otherwise null
+     * @since 3.0.0
+     */
+    public abstract Builder none(@Nullable Boolean none);
+
+    /**
+     * Build a new {@link MaxSpeed} object.
+     *
+     * @return a new {@link MaxSpeed} using the provided values in this builder
+     * @since 3.0.0
+     */
+    public abstract MaxSpeed build();
+  }
+}

services-directions/src/test/java/com/mapbox/api/directions/v5/models/MaxSpeedTest.java

@@ -0,0 +1,29 @@
+package com.mapbox.api.directions.v5.models;
+
+import com.mapbox.core.TestUtils;
+
+import org.junit.Test;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotNull;
+
+public class MaxSpeedTest extends TestUtils {
+
+  @Test
+  public void sanity() throws Exception {
+    MaxSpeed maxSpeed = MaxSpeed.builder()
+      .speed(65)
+      .unit("mph")
+      .build();
+    assertNotNull(maxSpeed);
+  }
+
+  @Test
+  public void testSerializable() throws Exception {
+    MaxSpeed maxSpeed = MaxSpeed.builder()
+      .unknown(true)
+      .build();
+    byte[] serialized = TestUtils.serialize(maxSpeed);
+    assertEquals(maxSpeed, deserialize(serialized, MaxSpeed.class));
+  }
+}