Merge pull request #1 from quartethealth/feature/add-annotations-to-matrix-service

Updates Matrix service.

Author: Mustafa Shabib

CHANGELOG.md

@@ -1,6 +1,9 @@
 ## Changelog for Mapbox Java and Android Services
 
 Mapbox welcomes participation and contributions from everyone.
+### v4.0.1 - September 27, 2018
+- Allows for annotations to be passed to the MatrixService and returns distances matrix in addition to durations matrix
+
 ### v4.0.0 - September 19, 2018
 - downgrade to java 7 #876
 - The first and last positions should be equivalent in polygon ring Bug Ready For Review refactor #886

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

@@ -66,7 +66,8 @@ protected Call<MatrixResponse> initializeCall() {
       coordinates(),
       accessToken(),
       destinations(),
-      sources());
+      sources(),
+      annotations());
   }
 
   @Nullable
@@ -90,6 +91,9 @@ protected Call<MatrixResponse> initializeCall() {
   @Nullable
   abstract String destinations();
 
+  @Nullable
+  abstract String annotations();
+
   @NonNull
   @Override
   protected abstract String baseUrl();
@@ -128,6 +132,7 @@ public abstract static class Builder {
     private List<Point> coordinates = new ArrayList<>();
     private Integer[] destinations;
     private Integer[] sources;
+    private String[] annotations;
 
     /**
      * The username for the account that the directions engine runs on. In most cases, this should
@@ -158,6 +163,22 @@ public Builder coordinates(List<Point> coordinates) {
     // Required for matching with MapboxMatrix coordinates() method.
     abstract Builder coordinates(@NonNull String coordinates);
 
+    /**
+     * Optionally pass in annotations to specify the resulting matrices. Possible values are:
+     * duration (default),  distance , or both values separated by comma.
+     *
+     * @param annotations "duration", "distance", or "duration,distance"
+     * @return this builder for chaining options together
+     * @since 2.1.0
+     */
+    public Builder annotations(@Nullable String... annotations) {
+      this.annotations = annotations;
+      return this;
+    }
+
+    // Required for matching with MapboxMatrix annotations() method.
+    abstract Builder annotations(@Nullable String annotations);
+
     /**
      * This will add a single {@link Point} to the coordinate list which is used to determine the
      * duration between points. This can be called up to 25 times until you hit the maximum allowed
@@ -264,6 +285,7 @@ public MapboxMatrix build() {
 
       sources(TextUtils.join(";", sources));
       destinations(TextUtils.join(";", destinations));
+      annotations(TextUtils.join(",", annotations));
 
       // 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

@@ -31,6 +31,9 @@ public interface MatrixService {
    *                     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 sources query
    *                     parameter
+   * @param annotations  Used to specify the resulting matrices. Possible values are:  duration
+   *                     (default),  distance , or both values separated by comma.
+   *
    * @return the {@link MatrixResponse} in a Call wrapper
    * @since 2.1.0
    */
@@ -43,6 +46,7 @@ Call<MatrixResponse> getCall(
     @Path("coordinates") String coordinates,
     @Query("access_token") String accessToken,
     @Query("destinations") String destinations,
-    @Query("sources") String sources
+    @Query("sources") String sources,
+    @Query("annotations") String annotations
   );
 }

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

@@ -83,6 +83,18 @@ public static Builder builder() {
   @Nullable
   public abstract List<Double[]> durations();
 
+  /**
+   * Distances as an array of arrays that represent 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 i
+   * meters. The distance between the same coordinate is always  0 . If a distance cannot be found
+   * the result is null .
+   *
+   * @return an array of array with each entry being a distance value given in meters.
+   * @since 2.1.1
+   */
+  @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 +179,18 @@ public abstract static class Builder {
      */
     public abstract Builder durations(@Nullable List<Double[]> durations);
 
+    /**
+     * Distances as array of arrays representing the matrix in row-major order. distances[i][j]
+     * gives the travel time 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 2.1.1
+     */
+    public abstract Builder distances(@Nullable List<Double[]> distances);
+
     /**
      * Build a new {@link MatrixResponse} object.
      *