added reverseMode parameter to Geocoding Service (#843)

Author: osana

services-geocoding/src/main/java/com/mapbox/api/geocoding/v5/GeocodingCriteria.java

@@ -96,6 +96,20 @@ public final class GeocodingCriteria {
    */
   public static final String TYPE_POI_LANDMARK = "poi.landmark";
 
+  /**
+   * Filter results by distance.
+   *
+   * @since 3.3.0
+   */
+  public static final String REVERSE_MODE_DISTANCE = "distance";
+
+  /**
+   * Filter results by score.
+   *
+   * @since 3.3.0
+   */
+  public static final String REVERSE_MODE_SCORE = "score";
+
   private GeocodingCriteria() {
     // Empty private constructor
   }
@@ -133,4 +147,18 @@ private GeocodingCriteria() {
   })
   public @interface GeocodingTypeCriteria {
   }
+
+
+  /**
+   * Retention policy for reverseMode filter result types.
+   *
+   * @since 3.0.0
+   */
+  @Retention(RetentionPolicy.SOURCE)
+  @StringDef( {
+    REVERSE_MODE_DISTANCE,
+    REVERSE_MODE_SCORE
+  })
+  public @interface GeocodingReverseModeCriteria {
+  }
 }

services-geocoding/src/main/java/com/mapbox/api/geocoding/v5/GeocodingService.java

@@ -33,6 +33,7 @@ public interface GeocodingService {
    * @param bbox         Optionally pass in a bounding box to limit results in.
    * @param limit        Optionally pass in a limit the amount of returning results.
    * @param language     The locale in which results should be returned.
+   * @param reverseMode  Set the factors that are used to sort nearby results.
    * @return A retrofit Call object
    * @since 1.0.0
    */
@@ -48,7 +49,8 @@ Call<GeocodingResponse> getCall(
     @Query("autocomplete") Boolean autocomplete,
     @Query("bbox") String bbox,
     @Query("limit") String limit,
-    @Query("language") String language);
+    @Query("language") String language,
+    @Query("reverseMode") String reverseMode);
 
   /**
    * Constructs the html call using the information passed in through the
@@ -66,6 +68,7 @@ Call<GeocodingResponse> getCall(
    * @param bbox         Optionally pass in a bounding box to limit results in.
    * @param limit        Optionally pass in a limit the amount of returning results.
    * @param language     The locale in which results should be returned.
+   * @param reverseMode  Set the factors that are used to sort nearby results.
    * @return A retrofit Call object
    * @since 1.0.0
    */
@@ -81,5 +84,6 @@ Call<List<GeocodingResponse>> getBatchCall(
     @Query("autocomplete") Boolean autocomplete,
     @Query("bbox") String bbox,
     @Query("limit") String limit,
-    @Query("language") String language);
+    @Query("language") String language,
+    @Query("reverseMode") String reverseMode);
 }

services-geocoding/src/main/java/com/mapbox/api/geocoding/v5/MapboxGeocoding.java

@@ -95,7 +95,8 @@ protected Call<GeocodingResponse> initializeCall() {
       autocomplete(),
       bbox(),
       limit(),
-      languages());
+      languages(),
+      reverseMode());
   }
 
   private Call<List<GeocodingResponse>> getBatchCall() {
@@ -119,7 +120,8 @@ private Call<List<GeocodingResponse>> getBatchCall() {
       autocomplete(),
       bbox(),
       limit(),
-      languages());
+      languages(),
+      reverseMode());
 
     return batchCall;
   }
@@ -203,6 +205,9 @@ public Call<List<GeocodingResponse>> cloneBatchCall() {
   @Nullable
   abstract String languages();
 
+  @Nullable
+  abstract String reverseMode();
+
   @Nullable
   abstract String clientAppName();
 
@@ -499,6 +504,20 @@ public Builder languages(Locale... languages) {
      */
     public abstract Builder languages(String languages);
 
+    /**
+     * Set the factors that are used to sort nearby results.
+     * Options avaliable to pass in include, {@link GeocodingCriteria#REVERSE_MODE_DISTANCE} for
+     * nearest feature result (default) or {@link GeocodingCriteria#REVERSE_MODE_SCORE}
+     * the notability of features within approximately 1 kilometer of the queried point
+     * along with proximity.
+     *
+     * @param reverseMode limit geocoding results based on the reverseMode
+     * @return this builder for chaining options together
+     * @since 3.3.0
+     */
+    public abstract Builder reverseMode(
+      @Nullable @GeocodingCriteria.GeocodingReverseModeCriteria String reverseMode);
+
     /**
      * Required to call when this is being built. If no access token provided,
      * {@link ServicesException} will be thrown.
@@ -552,6 +571,10 @@ public MapboxGeocoding build() {
         throw new ServicesException("A query with at least one character or digit is required.");
       }
 
+      if (geocoding.reverseMode() != null
+        && geocoding.limit() != null && !geocoding.limit().equals("1")) {
+        throw new ServicesException("Limit must be combined with a single type parameter");
+      }
       return geocoding;
     }
   }

services-geocoding/src/test/java/com/mapbox/api/geocoding/v5/MapboxGeocodingTest.java

@@ -220,4 +220,38 @@ public void clientAppName_hasAppInString() throws Exception {
       .build();
     assertTrue(mapboxGeocoding.cloneCall().request().header("User-Agent").contains("APP"));
   }
+
+  @Test
+  public void reverseMode_getsAddedToUrlCorrectly() throws Exception {
+    MapboxGeocoding mapboxGeocoding = MapboxGeocoding.builder()
+      .accessToken(ACCESS_TOKEN)
+      .baseUrl("https://foobar.com")
+      .query(Point.fromLngLat(-73.989,40.733))
+      .reverseMode(GeocodingCriteria.REVERSE_MODE_SCORE)
+      .build();
+    assertTrue(mapboxGeocoding.cloneCall().request().url().toString()
+      .contains("reverseMode=score"));
+
+    mapboxGeocoding = MapboxGeocoding.builder()
+      .accessToken(ACCESS_TOKEN)
+      .baseUrl("https://foobar.com")
+      .query(Point.fromLngLat(-73.989,40.733))
+      .reverseMode(GeocodingCriteria.REVERSE_MODE_DISTANCE)
+      .build();
+    assertTrue(mapboxGeocoding.cloneCall().request().url().toString()
+      .contains("reverseMode=distance"));
+  }
+
+  @Test
+  public void reverseMode_onlyLimit1_Allowed() throws Exception {
+    thrown.expect(ServicesException.class);
+    thrown.expectMessage(startsWith("Limit must be combined with a single type"));
+    MapboxGeocoding mapboxGeocoding = MapboxGeocoding.builder()
+      .accessToken(ACCESS_TOKEN)
+      .baseUrl("https://foobar.com")
+      .query(Point.fromLngLat(-73.989,40.733))
+      .reverseMode(GeocodingCriteria.REVERSE_MODE_SCORE)
+      .limit(2)
+      .build();
+  }
 }