Add annotations, approaches request parameter & distances to the response object (#911)

* adding a distance component to the matrix response

* adding documentation

* adding more documentation

* fixing documentation

* removing annotation enum since it already exists

* updated fixtures, tests
added approaches

Author: osana

Makefile

@@ -48,12 +48,16 @@ graphs:
 	./gradlew :services-turf:generateDependencyGraphMapboxLibraries
 
 directions-matrix-fixtures:
+	# request a symmetric 1x3 matrix for pedestrians
+	curl "https://api.mapbox.com/directions-matrix/v1/mapbox/walking/-122.42,37.78;-122.45,37.91;-122.48,37.73?sources=1&annotations=distance,duration&approaches=curb;curb;curb&access_token=$(MAPBOX_ACCESS_TOKEN)" \
+		-o services-matrix/src/test/resources/directions_matrix_1x3.json
+
 	# request a symmetric 3x3 matrix for cars
 	curl "https://api.mapbox.com/directions-matrix/v1/mapbox/driving/-122.42,37.78;-122.45,37.91;-122.48,37.73?access_token=$(MAPBOX_ACCESS_TOKEN)" \
 		-o services-matrix/src/test/resources/directions_matrix_3x3.json
 
 	# request an asymmetric 2x3 matrix for bicycles
-	curl "https://api.mapbox.com/directions-matrix/v1/mapbox/cycling/-122.42,37.78;-122.45,37.91;-122.48,37.73?sources=0;2&destinations=all&access_token=$(MAPBOX_ACCESS_TOKEN)" \
+	curl "https://api.mapbox.com/directions-matrix/v1/mapbox/cycling/-122.42,37.78;-122.45,37.91;-122.48,37.73?sources=0;2&access_token=$(MAPBOX_ACCESS_TOKEN)" \
 		-o services-matrix/src/test/resources/directions_matrix_2x3.json
 
 geocoding-fixtures:

services-matrix/src/main/java/com/mapbox/api/matrix/v1/MapboxMatrix.java

@@ -65,6 +65,8 @@ protected Call<MatrixResponse> initializeCall() {
       profile(),
       coordinates(),
       accessToken(),
+      annotations(),
+      approaches(),
       destinations(),
       sources());
   }
@@ -87,6 +89,12 @@ protected Call<MatrixResponse> initializeCall() {
   @Nullable
   abstract String sources();
 
+  @Nullable
+  abstract String annotations();
+
+  @Nullable
+  abstract String approaches();
+
   @Nullable
   abstract String destinations();
 
@@ -126,6 +134,8 @@ public static Builder builder() {
   public abstract static class Builder {
 
     private List<Point> coordinates = new ArrayList<>();
+    private String[] annotations;
+    private String[] approaches;
     private Integer[] destinations;
     private Integer[] sources;
 
@@ -175,9 +185,10 @@ public Builder coordinate(@NonNull Point coordinate) {
     /**
      * This selects which mode of transportation the user will be using to accurately give the
      * matrix durations. The options include driving, driving considering traffic, walking, and
-     * cycling. Using each of these profiles will result in different durations
+     * cycling. Using each of these profiles will result in different durations.
      *
-     * @param profile required to be one of the String values found in the {@link ProfileCriteria}
+     * @param profile required to be one of the String values found in the
+     *                {@link ProfileCriteria}
      * @return this builder for chaining options together
      * @since 2.1.0
      */
@@ -194,6 +205,46 @@ public Builder coordinate(@NonNull Point coordinate) {
      */
     public abstract Builder accessToken(@NonNull String accessToken);
 
+
+    /**
+     * Optionally pass in annotations to control to change which data to return.
+     *
+     * @param annotations 1 or more annotations
+     * @return this builder for chaining options together
+     * @since 4.1.0
+     */
+    public Builder addAnnotations(
+            @Nullable @DirectionsCriteria.AnnotationCriteria String... annotations) {
+      this.annotations = annotations;
+      return this;
+    }
+
+    // Required for matching with MapboxMatrix annotations() method.
+    abstract Builder annotations(@Nullable String annotations);
+
+    /**
+     * A semicolon-separated list indicating the side of the road from
+     * which to approach waypoints in a requested route.
+     * Accepts  unrestricted (default, route can arrive at the waypoint from either
+     * side of the road) or  curb (route will arrive at the waypoint on
+     * the  driving_side of the region).
+     * If provided, the number of approaches must be the same as the number of waypoints.
+     * However, you can skip a coordinate and show its position in the list with the ; separator.
+     *
+     * @param approaches null if you'd like the default approaches,
+     *                   else one of the options found in
+     *                   {@link com.mapbox.api.directions.v5.DirectionsCriteria.ApproachesCriteria}.
+     * @return this builder for chaining options together
+     * @since 4.1.0
+     */
+    public Builder addApproaches(@Nullable String... approaches) {
+      this.approaches = approaches;
+      return this;
+    }
+
+    abstract Builder approaches(
+            @Nullable @DirectionsCriteria.ApproachesCriteria String approaches);
+
     /**
      * Optionally pass in indexes to generate an asymmetric matrix.
      *
@@ -264,6 +315,8 @@ public MapboxMatrix build() {
 
       sources(TextUtils.join(";", sources));
       destinations(TextUtils.join(";", destinations));
+      annotations(TextUtils.join(",", annotations));
+      approaches(TextUtils.join(";", approaches));
 
       // Generate build so that we can check that values are valid.
       MapboxMatrix matrix = autoBuild();

services-matrix/src/main/java/com/mapbox/api/matrix/v1/MatrixService.java

@@ -23,6 +23,18 @@ public interface MatrixService {
    * @param profile      the profile directions should use
    * @param coordinates  the coordinates the route should follow
    * @param accessToken  Mapbox access token
+   * @param annotations  Used to specify the resulting matrices.
+   *                     Possible values are: duration (default),
+   *                     distance, or both values separated by comma
+   * @param approaches   A semicolon-separated list indicating the side of the road from
+   *                     which to approach waypoints in a requested route.
+   *                     Accepts  unrestricted (default, route can arrive at the waypoint
+   *                     from either side of the road) or  curb (route will arrive at
+   *                     the waypoint on the  driving_side of the region).
+   *                     If provided, the number of approaches must be the same
+   *                     as the number of waypoints.
+   *                     However, you can skip a coordinate and
+   *                     show its position in the list with the  ; separator.
    * @param destinations array of waypoint objects. Each waypoints is an input coordinate snapped to
    *                     the road and path network. The waypoints appear in the array in the order
    *                     of the input coordinates, or in the order as specified in the destinations
@@ -42,6 +54,8 @@ Call<MatrixResponse> getCall(
     @Path("profile") String profile,
     @Path("coordinates") String coordinates,
     @Query("access_token") String accessToken,
+    @Query("annotations") String annotations,
+    @Query("approaches") String approaches,
     @Query("destinations") String destinations,
     @Query("sources") String sources
   );

services-matrix/src/main/java/com/mapbox/api/matrix/v1/models/MatrixResponse.java

@@ -1,14 +1,15 @@
 package com.mapbox.api.matrix.v1.models;
 
-import android.support.annotation.NonNull;
+import java.io.Serializable;
+import java.util.List;
+
 import android.support.annotation.Nullable;
 import com.google.auto.value.AutoValue;
 import com.google.gson.Gson;
 import com.google.gson.TypeAdapter;
 import com.mapbox.api.directions.v5.models.DirectionsWaypoint;
 
-import java.io.Serializable;
-import java.util.List;
+import android.support.annotation.NonNull;
 
 /**
  * This contains the Matrix API response information which can be used to display the results.
@@ -83,6 +84,18 @@ public static Builder builder() {
   @Nullable
   public abstract List<Double[]> durations();
 
+  /**
+   * Distances as a list of arrays representing the matrix in row-major order.
+   * distances[i][j] gives the travel distance from the i-th source to the j-th destination.
+   * All values are in meters. The duration between the same coordinate is always 0.
+   * If a distance can not be found, the result is null.
+   *
+   * @return an array of array with each entry being a distance value given in meters.
+   * @since 4.1.0
+   */
+  @Nullable
+  public abstract List<Double[]> distances();
+
   /**
    * Convert the current {@link MatrixResponse} to its builder holding the currently assigned
    * values. This allows you to modify a single variable and then rebuild the object resulting in
@@ -167,6 +180,18 @@ public abstract static class Builder {
      */
     public abstract Builder durations(@Nullable List<Double[]> durations);
 
+    /**
+     * Distances as a list of arrays representing the matrix in row-major order.
+     * distances[i][j] gives the travel distance from the i-th source to the j-th destination.
+     * All values are in meters. The duration between the same coordinate is always 0.
+     * If a distance can not be found, the result is null.
+     *
+     * @param distances an array of array with each entry being a distance value given in meters
+     * @return this builder for chaining options together
+     * @since 4.1.0
+     */
+    public abstract Builder distances(@Nullable List<Double[]> distances);
+
     /**
      * Build a new {@link MatrixResponse} object.
      *

services-matrix/src/test/java/com/mapbox/api/matrix/v1/MapboxMatrixTest.java

@@ -22,15 +22,19 @@
 import okhttp3.mockwebserver.RecordedRequest;
 import retrofit2.Response;
 
+import static com.mapbox.api.directions.v5.DirectionsCriteria.ANNOTATION_DISTANCE;
+import static com.mapbox.api.directions.v5.DirectionsCriteria.ANNOTATION_DURATION;
+import static com.mapbox.api.directions.v5.DirectionsCriteria.APPROACH_CURB;
 import static org.hamcrest.core.StringStartsWith.startsWith;
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertNotNull;
 import static org.junit.Assert.assertTrue;
 
 public class MapboxMatrixTest extends TestUtils {
 
-  private static final String DIRECTIONS_MATRIX_3X3_FIXTURE = "directions_matrix_3x3.json";
-  private static final String DIRECTIONS_MATRIX_2x3_FIXTURE = "directions_matrix_2x3.json";
+  private static final String DIRECTIONS_MATRIX_WALKING_1X3_FIXTURE = "directions_matrix_1x3.json";
+  private static final String DIRECTIONS_MATRIX_CYCLING_2X3_FIXTURE = "directions_matrix_2x3.json";
+  private static final String DIRECTIONS_MATRIX_DRIVING_3X3_FIXTURE = "directions_matrix_3x3.json";
 
   private MockWebServer server;
   private HttpUrl mockUrl;
@@ -49,7 +53,17 @@ public void setUp() throws IOException {
       @Override
       public MockResponse dispatch(RecordedRequest request) throws InterruptedException {
         try {
-          String response = loadJsonFixture(DIRECTIONS_MATRIX_3X3_FIXTURE);
+          String resource;
+          if (request.getPath().contains("walking")) {
+            resource = DIRECTIONS_MATRIX_WALKING_1X3_FIXTURE;
+
+          } else if (request.getPath().contains("cycling")) {
+            resource = DIRECTIONS_MATRIX_CYCLING_2X3_FIXTURE;
+
+          } else { // driving
+            resource = DIRECTIONS_MATRIX_DRIVING_3X3_FIXTURE;
+          }
+          String response = loadJsonFixture(resource);
           return new MockResponse().setBody(response);
         } catch (IOException ioException) {
           throw new RuntimeException(ioException);
@@ -77,7 +91,7 @@ public void tearDown() throws IOException {
   public void testCallSanity() throws ServicesException, IOException {
     MapboxMatrix client = MapboxMatrix.builder()
       .accessToken(ACCESS_TOKEN)
-      .profile(DirectionsCriteria.PROFILE_WALKING)
+      .profile(DirectionsCriteria.PROFILE_DRIVING)
       .coordinates(positions)
       .baseUrl(mockUrl.toString())
       .build();
@@ -88,6 +102,7 @@ public void testCallSanity() throws ServicesException, IOException {
     assertNotNull(response.body());
     assertEquals(3, response.body().destinations().size());
     assertNotNull(response.body().destinations().get(0).name());
+    assertEquals(3, response.body().durations().size());
   }
 
   @Test
@@ -155,19 +170,56 @@ public void testUserAgent() throws ServicesException, IOException {
   }
 
   @Test
-  public void testResponse() throws ServicesException, IOException {
+  public void request_containsAnnotations() throws ServicesException, IOException {
+    MapboxMatrix client = MapboxMatrix.builder()
+            .accessToken(ACCESS_TOKEN)
+            .profile(DirectionsCriteria.PROFILE_WALKING)
+            .coordinates(positions)
+            .addAnnotations(ANNOTATION_DISTANCE, ANNOTATION_DURATION)
+            .sources(0, 2)
+            .build();
+
+    assertTrue(client.cloneCall()
+            .request().url().toString()
+            .contains("annotations=distance"));
+  }
+
+  @Test
+  public void request_containsApproaches() throws ServicesException, IOException {
+    MapboxMatrix client = MapboxMatrix.builder()
+            .accessToken(ACCESS_TOKEN)
+            .profile(DirectionsCriteria.PROFILE_WALKING)
+            .coordinates(positions)
+            .addApproaches(APPROACH_CURB, APPROACH_CURB, APPROACH_CURB)
+            .build();
+
+    String c = client.cloneCall().request().url().toString();
+
+
+    assertTrue(c.contains("approaches=curb"));
+  }
+
+  @Test
+  public void annotationsAndApproaches() throws ServicesException, IOException {
     MapboxMatrix client = MapboxMatrix.builder()
       .accessToken(ACCESS_TOKEN)
-      .profile(DirectionsCriteria.PROFILE_DRIVING)
+      .profile(DirectionsCriteria.PROFILE_WALKING)
       .coordinates(positions)
+      .addAnnotations(ANNOTATION_DISTANCE, ANNOTATION_DURATION)
+      .addApproaches(APPROACH_CURB, APPROACH_CURB, APPROACH_CURB)
+      .sources(0,2)
       .baseUrl(mockUrl.toString())
       .build();
-    Response<MatrixResponse> response = client.executeCall();
 
-    assertEquals(response.body().sources().size(), 3);
-    assertEquals(response.body().sources().get(0).location().longitude(), -122.420019, DELTA);
-    assertEquals(response.body().destinations().get(0).location().longitude(), -122.420019, DELTA);
-//    assertEquals(response.body().durations().get(0), 1888.3, DELTA);
-    assertEquals(response.body().destinations().get(0).name(), "McAllister Street");
+    Response<MatrixResponse> response = client.executeCall();
+    assertEquals(200, response.code());
+    assertEquals(1, response.body().sources().size());
+    assertEquals(1, response.body().distances().size());
+    assertEquals(1, response.body().durations().size());
+    assertEquals(-122.461997, response.body().sources().get(0).location().longitude(), DELTA);
+    assertEquals(-122.420019, response.body().destinations().get(0).location().longitude(),  DELTA);
+    assertEquals(19711.7, response.body().durations().get(0)[2], DELTA);
+    assertEquals(27192.3, response.body().distances().get(0)[2], DELTA);
+    assertEquals("McAllister Street", response.body().destinations().get(0).name());
   }
 }

services-matrix/src/test/resources/directions_matrix_1x3.json

@@ -0,0 +1,49 @@
+{
+  "distances": [
+    [
+      18664.5,
+      0,
+      27192.3
+    ]
+  ],
+  "durations": [
+    [
+      13490.5,
+      0,
+      19711.7
+    ]
+  ],
+  "destinations": [
+    {
+      "name": "McAllister Street",
+      "location": [
+        -122.420019,
+        37.780091
+      ]
+    },
+    {
+      "name": "Playa Verde",
+      "location": [
+        -122.461997,
+        37.89621
+      ]
+    },
+    {
+      "name": "",
+      "location": [
+        -122.480005,
+        37.730039
+      ]
+    }
+  ],
+  "sources": [
+    {
+      "name": "Playa Verde",
+      "location": [
+        -122.461997,
+        37.89621
+      ]
+    }
+  ],
+  "code": "Ok"
+}