Batch geocoding support (#267)

* new geocoding batch fixture

* add a new geocoding-batch-fixtures rule and fix the paths

* reformat fixture for easy reading

* add batch methods and tests

* update @SInCE 2.0.0 tags

* remove unnecessary code from MapboxGeocodingBatchTest

* o o p s

Author: zugaldia

Makefile

@@ -55,33 +55,37 @@ dex-count:
 geocoding-fixtures:
 	# Geocoding: 1600 Pennsylvania Ave NW
 	curl "https://api.mapbox.com/geocoding/v5/mapbox.places/1600+pennsylvania+ave+nw.json?access_token=$(MAPBOX_ACCESS_TOKEN)" \
-		-o libjava/lib/src/test/fixtures/geocoding.json
+		-o mapbox/libjava-services/src/test/fixtures/geocoding.json
 
 	# Reverse geocoding: -77.0366, 38.8971
 	curl "https://api.mapbox.com/geocoding/v5/mapbox.places/-77.0366,38.8971.json?access_token=$(MAPBOX_ACCESS_TOKEN)" \
-		-o libjava/lib/src/test/fixtures/geocoding_reverse.json
+		-o mapbox/libjava-services/src/test/fixtures/geocoding_reverse.json
 
-	#
+	# Not supported country
 	curl "https://api.mapbox.com/geocoding/v5/mapbox.places/1600+pennsylvania+ave+nw.json?country=aq&access_token=$(MAPBOX_ACCESS_TOKEN)" \
-	  -o libjava/lib/src/test/fixtures/geocoding_country_not_supported.json
+		-o mapbox/libjava-services/src/test/fixtures/geocoding_country_not_supported.json
+
+geocoding-batch-fixtures:
+	curl "https://api.mapbox.com/geocoding/v5/mapbox.places-permanent/20001;20009;22209.json?access_token=$(MAPBOX_ACCESS_TOKEN)" \
+		-o mapbox/libjava-services/src/test/fixtures/geocoding_batch.json
 
 directions-fixtures:
 	curl "https://api.mapbox.com/directions/v5/mapbox/driving/-122.416667,37.783333;-121.900000,37.333333?geometries=polyline&steps=true&access_token=$(MAPBOX_ACCESS_TOKEN)" \
-		-o libjava/lib/src/test/fixtures/directions_v5.json
+		-o mapbox/libjava-services/src/test/fixtures/directions_v5.json
 
 mapmatching-fixtures:
 	# Geometry polyline
-	curl -X POST --header "Content-Type:application/json" -d @libjava/lib/src/test/fixtures/mapmatching_trace.json \
+	curl -X POST --header "Content-Type:application/json" -d @mapbox/libjava-services/src/test/fixtures/mapmatching_trace.json \
 		"https://api.mapbox.com/matching/v4/mapbox.driving.json?geometry=polyline&access_token=$(MAPBOX_ACCESS_TOKEN)" \
-		-o libjava/lib/src/test/fixtures/mapmatching_v5_polyline.json
+		-o mapbox/libjava-services/src/test/fixtures/mapmatching_v5_polyline.json
 
 	# No geometry
-	curl -X POST --header "Content-Type:application/json" -d @libjava/lib/src/test/fixtures/mapmatching_trace.json \
+	curl -X POST --header "Content-Type:application/json" -d @mapbox/libjava-services/src/test/fixtures/mapmatching_trace.json \
 		"https://api.mapbox.com/matching/v4/mapbox.driving.json?geometry=false&access_token=$(MAPBOX_ACCESS_TOKEN)" \
-		-o libjava/lib/src/test/fixtures/mapmatching_v5_no_geometry.json
+		-o mapbox/libjava-services/src/test/fixtures/mapmatching_v5_no_geometry.json
 
 distance-fixtures:
 	# Retrieve a duration matrix
-	curl -X POST --header "Content-Type:application/json" -d @libjava/lib/src/test/fixtures/distance_coordinates.json \
+	curl -X POST --header "Content-Type:application/json" -d @mapbox/libjava-services/src/test/fixtures/distance_coordinates.json \
 		"https://api.mapbox.com/distances/v1/mapbox/driving?access_token=$(MAPBOX_ACCESS_TOKEN)" \
-		-o libjava/lib/src/test/fixtures/distance_v1.json
+		-o mapbox/libjava-services/src/test/fixtures/distance_v1.json

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

@@ -2,6 +2,8 @@
 
 import com.mapbox.services.api.geocoding.v5.models.GeocodingResponse;
 
+import java.util.List;
+
 import retrofit2.Call;
 import retrofit2.http.GET;
 import retrofit2.http.Header;
@@ -19,7 +21,7 @@ public interface GeocodingService {
    * Call-based interface
    *
    * @param userAgent    The user
-   * @param mode         mapbox.places or mapbox.places-permanent for enterprise/batch geocoding.
+   * @param mode         mapbox.places or mapbox.places-permanent for enterprise geocoding.
    * @param query        a location; a place name for forward geocoding or a coordinate pair
    *                     (longitude, latitude location) for reverse geocoding
    * @param accessToken  Mapbox access token.
@@ -44,4 +46,34 @@ Call<GeocodingResponse> getCall(
     @Query("autocomplete") Boolean autocomplete,
     @Query("bbox") String bbox,
     @Query("limit") String limit);
+
+  /**
+   * Call-based interface
+   *
+   * @param userAgent    The user
+   * @param mode         mapbox.places-permanent for batch geocoding.
+   * @param query        a location; a place name for forward geocoding or a coordinate pair
+   *                     (longitude, latitude location) for reverse geocoding
+   * @param accessToken  Mapbox access token.
+   * @param country      ISO 3166 alpha 2 country codes, separated by commas.
+   * @param proximity    Location around which to bias results.
+   * @param types        Filter results by one or more type.
+   * @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.
+   * @return A retrofit Call object
+   * @since 1.0.0
+   */
+  @GET("/geocoding/v5/{mode}/{query}.json")
+  Call<List<GeocodingResponse>> getBatchCall(
+    @Header("User-Agent") String userAgent,
+    @Path("mode") String mode,
+    @Path("query") String query,
+    @Query("access_token") String accessToken,
+    @Query("country") String country,
+    @Query("proximity") String proximity,
+    @Query("types") String types,
+    @Query("autocomplete") Boolean autocomplete,
+    @Query("bbox") String bbox,
+    @Query("limit") String limit);
 }

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

@@ -12,6 +12,7 @@
 import com.mapbox.services.api.geocoding.v5.models.GeocodingResponse;
 
 import java.io.IOException;
+import java.util.List;
 import java.util.Locale;
 
 import retrofit2.Call;
@@ -30,6 +31,7 @@ public class MapboxGeocoding extends MapboxService<GeocodingResponse> {
   private Builder builder = null;
   private GeocodingService service = null;
   private Call<GeocodingResponse> call = null;
+  private Call<List<GeocodingResponse>> batchCall = null;
 
   /**
    * Public constructor.
@@ -80,6 +82,10 @@ public Call<GeocodingResponse> getCall() {
       return call;
     }
 
+    if (builder.getQuery().contains(";")) {
+      throw new IllegalArgumentException("Use getBatchCall() for batch calls.");
+    }
+
     call = getService().getCall(
       getHeaderUserAgent(builder.getClientAppName()),
       builder.getMode(),
@@ -95,6 +101,37 @@ public Call<GeocodingResponse> getCall() {
     return call;
   }
 
+  /**
+   * Used internally.
+   *
+   * @return batch call
+   * @since 2.0.0
+   */
+  public Call<List<GeocodingResponse>> getBatchCall() {
+    // No need to recreate it
+    if (batchCall != null) {
+      return batchCall;
+    }
+
+    if (!builder.getQuery().contains(";")) {
+      throw new IllegalArgumentException("Use getCall() for non-batch calls.");
+    }
+
+    batchCall = getService().getBatchCall(
+      getHeaderUserAgent(builder.getClientAppName()),
+      builder.getMode(),
+      builder.getQuery(),
+      builder.getAccessToken(),
+      builder.getCountry(),
+      builder.getProximity(),
+      builder.getGeocodingTypes(),
+      builder.getAutocomplete(),
+      builder.getBbox(),
+      builder.getLimit());
+
+    return batchCall;
+  }
+
   /**
    * Execute the call
    *
@@ -107,6 +144,17 @@ public Response<GeocodingResponse> executeCall() throws IOException {
     return getCall().execute();
   }
 
+  /**
+   * Execute the batch call
+   *
+   * @return The Geocoding v5 response
+   * @throws IOException Signals that an I/O exception of some sort has occurred.
+   * @since 2.0.0
+   */
+  public Response<List<GeocodingResponse>> executeBatchCall() throws IOException {
+    return getBatchCall().execute();
+  }
+
   /**
    * Execute the call
    *
@@ -118,6 +166,16 @@ public void enqueueCall(Callback<GeocodingResponse> callback) {
     getCall().enqueue(callback);
   }
 
+  /**
+   * Execute the batch call
+   *
+   * @param callback A Retrofit callback.
+   * @since 2.0.0
+   */
+  public void enqueueBatchCall(Callback<List<GeocodingResponse>> callback) {
+    getBatchCall().enqueue(callback);
+  }
+
   /**
    * Cancel the call
    *
@@ -128,6 +186,15 @@ public void cancelCall() {
     getCall().cancel();
   }
 
+  /**
+   * Cancel the batch call
+   *
+   * @since 2.0.0
+   */
+  public void cancelBatchCall() {
+    getBatchCall().cancel();
+  }
+
   /**
    * clone the call
    *
@@ -139,6 +206,16 @@ public Call<GeocodingResponse> cloneCall() {
     return getCall().clone();
   }
 
+  /**
+   * clone the batch call
+   *
+   * @return cloned call
+   * @since 2.0.0
+   */
+  public Call<List<GeocodingResponse>> cloneBatchCall() {
+    return getBatchCall().clone();
+  }
+
   /**
    * Builds your geocoder query by adding parameters.
    *