Add optional language parameter to geocoder (#315)

* add new test for geocoding language

* add new param to services and clients

* expose language param to widget

Author: zugaldia

mapbox/libandroid-ui/src/main/java/com/mapbox/services/android/ui/geocoder/GeocoderAdapter.java

@@ -39,6 +39,7 @@ public class GeocoderAdapter extends BaseAdapter implements Filterable {
   private double[] bbox;
   private Position position;
   private int limit;
+  private String language;
   private Call call;
 
   private GeocoderFilter geocoderFilter;
@@ -250,6 +251,35 @@ public void setLimit(int limit) {
     this.limit = limit;
   }
 
+  /**
+   * @return The locale in which results should be returned.
+   * @since 2.0.0
+   */
+  public String getLanguage() {
+    return language;
+  }
+
+  /**
+   * The locale in which results should be returned.
+   * <p>
+   * This property affects the language of returned results; generally speaking,
+   * it does not determine which results are found. If the Geocoding API does not
+   * recognize the language code, it may fall back to another language or the default
+   * language. Components other than the language code, such as the country and
+   * script codes, are ignored.
+   * <p>
+   * By default, this property is set to `null`, causing results to be in the default
+   * language.
+   * <p>
+   * This option is experimental.
+   *
+   * @param language The locale in which results should be returned.
+   * @since 2.0.0
+   */
+  public void setLanguage(String language) {
+    this.language = language;
+  }
+
   /**
    * Can be used to cancel any calls currently in progress. It's a good idea to include in onDestroy() to prevent
    * memory leaks
@@ -405,6 +435,9 @@ protected FilterResults performFiltering(CharSequence constraint) {
         if (getLimit() != 0) {
           builder.setLimit(limit);
         }
+        if (getLanguage() != null) {
+          builder.setLanguage(language);
+        }
 
         call = builder.build().getCall();
 

mapbox/libandroid-ui/src/main/java/com/mapbox/services/android/ui/geocoder/GeocoderAutoCompleteView.java

@@ -207,6 +207,27 @@ public void setLimit(int limit) {
     adapter.setLimit(limit);
   }
 
+  /**
+   * The locale in which results should be returned.
+   * <p>
+   * This property affects the language of returned results; generally speaking,
+   * it does not determine which results are found. If the Geocoding API does not
+   * recognize the language code, it may fall back to another language or the default
+   * language. Components other than the language code, such as the country and
+   * script codes, are ignored.
+   * <p>
+   * By default, this property is set to `null`, causing results to be in the default
+   * language.
+   * <p>
+   * This option is experimental.
+   *
+   * @param language The locale in which results should be returned.
+   * @since 2.0.0
+   */
+  public void setLanguage(String language) {
+    adapter.setLanguage(language);
+  }
+
   /**
    * Sets the listener that will be notified when the user clicks an item in the drop down list.
    *

mapbox/libjava-services-rx/src/main/java/com/mapbox/services/api/rx/geocoding/v5/GeocodingServiceRx.java

@@ -31,6 +31,7 @@ public interface GeocodingServiceRx {
    * @param autocomplete True if you want auto complete.
    * @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.
    * @return A retrofit Observable object
    * @since 1.0.0
    */
@@ -45,7 +46,8 @@ Observable<GeocodingResponse> getObservable(
     @Query("types") String types,
     @Query("autocomplete") Boolean autocomplete,
     @Query("bbox") String bbox,
-    @Query("limit") String limit);
+    @Query("limit") String limit,
+    @Query("language") String language);
 
   /**
    * Observable-based interface
@@ -61,6 +63,7 @@ Observable<GeocodingResponse> getObservable(
    * @param autocomplete True if you want auto complete.
    * @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.
    * @return A retrofit Observable object
    * @since 1.0.0
    */
@@ -75,5 +78,6 @@ Observable<List<GeocodingResponse>> getBatchObservable(
     @Query("types") String types,
     @Query("autocomplete") Boolean autocomplete,
     @Query("bbox") String bbox,
-    @Query("limit") String limit);
+    @Query("limit") String limit,
+    @Query("language") String language);
 }

mapbox/libjava-services-rx/src/main/java/com/mapbox/services/api/rx/geocoding/v5/MapboxGeocodingRx.java

@@ -67,7 +67,8 @@ public Observable<GeocodingResponse> getObservable() {
       builder.getGeocodingTypes(),
       builder.getAutocomplete(),
       builder.getBbox(),
-      builder.getLimit());
+      builder.getLimit(),
+      builder.getLanguage());
 
     // Done
     return observable;
@@ -93,7 +94,8 @@ public Observable<List<GeocodingResponse>> getBatchObservable() {
       builder.getGeocodingTypes(),
       builder.getAutocomplete(),
       builder.getBbox(),
-      builder.getLimit());
+      builder.getLimit(),
+      builder.getLanguage());
 
     // Done
     return batchObservable;

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

@@ -31,6 +31,7 @@ public interface GeocodingService {
    * @param autocomplete True if you want auto complete.
    * @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.
    * @return A retrofit Call object
    * @since 1.0.0
    */
@@ -46,7 +47,8 @@ Call<GeocodingResponse> getCall(
     @Query("types") String types,
     @Query("autocomplete") Boolean autocomplete,
     @Query("bbox") String bbox,
-    @Query("limit") String limit);
+    @Query("limit") String limit,
+    @Query("language") String language);
 
   /**
    * Call-based interface
@@ -62,6 +64,7 @@ Call<GeocodingResponse> getCall(
    * @param autocomplete True if you want auto complete.
    * @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.
    * @return A retrofit Call object
    * @since 1.0.0
    */
@@ -77,5 +80,6 @@ Call<List<GeocodingResponse>> getBatchCall(
     @Query("types") String types,
     @Query("autocomplete") Boolean autocomplete,
     @Query("bbox") String bbox,
-    @Query("limit") String limit);
+    @Query("limit") String limit,
+    @Query("language") String language);
 }

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

@@ -5,11 +5,11 @@
 import com.mapbox.services.api.MapboxBuilder;
 import com.mapbox.services.api.MapboxService;
 import com.mapbox.services.api.ServicesException;
+import com.mapbox.services.api.geocoding.v5.gson.CarmenGeometryDeserializer;
+import com.mapbox.services.api.geocoding.v5.models.GeocodingResponse;
 import com.mapbox.services.commons.geojson.Geometry;
 import com.mapbox.services.commons.models.Position;
 import com.mapbox.services.commons.utils.TextUtils;
-import com.mapbox.services.api.geocoding.v5.gson.CarmenGeometryDeserializer;
-import com.mapbox.services.api.geocoding.v5.models.GeocodingResponse;
 
 import java.io.IOException;
 import java.util.List;
@@ -103,7 +103,8 @@ public Call<GeocodingResponse> getCall() {
       builder.getGeocodingTypes(),
       builder.getAutocomplete(),
       builder.getBbox(),
-      builder.getLimit());
+      builder.getLimit(),
+      builder.getLanguage());
 
     return call;
   }
@@ -134,7 +135,8 @@ public Call<List<GeocodingResponse>> getBatchCall() {
       builder.getGeocodingTypes(),
       builder.getAutocomplete(),
       builder.getBbox(),
-      builder.getLimit());
+      builder.getLimit(),
+      builder.getLanguage());
 
     return batchCall;
   }
@@ -242,6 +244,7 @@ public static class Builder<T extends Builder> extends MapboxBuilder {
     private Boolean autocomplete = null;
     private String bbox = null;
     private String limit = null;
+    private String language = null;
 
     /**
      * Constructor
@@ -513,6 +516,37 @@ public String getLimit() {
       return limit;
     }
 
+    /**
+     * @return The locale in which results should be returned.
+     * @since 2.0.0
+     */
+    public String getLanguage() {
+      return language;
+    }
+
+    /**
+     * The locale in which results should be returned.
+     *
+     * This property affects the language of returned results; generally speaking,
+     * it does not determine which results are found. If the Geocoding API does not
+     * recognize the language code, it may fall back to another language or the default
+     * language. Components other than the language code, such as the country and
+     * script codes, are ignored.
+     *
+     * By default, this property is set to `null`, causing results to be in the default
+     * language.
+     *
+     * This option is experimental.
+     *
+     * @param language The locale in which results should be returned.
+     * @return the current MapboxBuilder instance
+     * @since 2.0.0
+     */
+    public T setLanguage(String language) {
+      this.language = language;
+      return (T) this;
+    }
+
     public T setClientAppName(String appName) {
       super.clientAppName = appName;
       return (T) this;

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

@@ -18,6 +18,7 @@
 import java.nio.file.Files;
 import java.nio.file.Paths;
 import java.util.List;
+import java.util.Locale;
 
 import okhttp3.HttpUrl;
 import okhttp3.mockwebserver.Dispatcher;
@@ -197,4 +198,26 @@ public void testCountryNotSupported() throws ServicesException, IOException {
 
     assertEquals(0, response.body().getFeatures().size());
   }
+
+  @Test
+  public void testLanguage() throws IOException, ServicesException {
+    MapboxGeocoding clientNoLanguage = new MapboxGeocoding.Builder()
+      .setAccessToken(ACCESS_TOKEN)
+      .setLocation("1600 pennsylvania ave nw")
+      .setBaseUrl(mockUrl.toString())
+      .build();
+
+    // By default no language is included
+    assertTrue(!clientNoLanguage.getCall().request().url().toString().contains("language=en_GB"));
+
+    MapboxGeocoding clientLanguage = new MapboxGeocoding.Builder()
+      .setAccessToken(ACCESS_TOKEN)
+      .setLocation("1600 pennsylvania ave nw")
+      .setLanguage(Locale.UK.toString())
+      .setBaseUrl(mockUrl.toString())
+      .build();
+
+    // setLanguage() will include the language query parameter
+    assertTrue(clientLanguage.getCall().request().url().toString().contains("language=en_GB"));
+  }
 }