Geocoding V6 Support (#1577)

* V6 preview

* V6 full support

* Code review

* Adding V6FeatureType.SECONDARY_ADDRESS & address_line1

* Adding name_preferred, full_address and bbox to V6Properties

* Adding coordinates.routable_points

* Adding V6ContextAddress

* Updating java docs

---------

Co-authored-by: Dzmitry Fomchyn <[email protected]>
Co-authored-by: dzmitryfomchyn <[email protected]>

samples/src/main/java/com/mapbox/samples/BasicV6BatchGeocoding.java

@@ -0,0 +1,93 @@
+package com.mapbox.samples;
+
+import com.mapbox.api.geocoding.v6.MapboxV6BatchGeocoding;
+import com.mapbox.api.geocoding.v6.V6RequestOptions;
+import com.mapbox.api.geocoding.v6.V6StructuredInputQuery;
+import com.mapbox.api.geocoding.v6.V6ForwardGeocodingRequestOptions;
+import com.mapbox.api.geocoding.v6.models.V6BatchResponse;
+import com.mapbox.api.geocoding.v6.models.V6Feature;
+import com.mapbox.api.geocoding.v6.models.V6FeatureType;
+import com.mapbox.api.geocoding.v6.models.V6Response;
+import com.mapbox.api.geocoding.v6.V6ReverseGeocodingRequestOptions;
+import com.mapbox.geojson.BoundingBox;
+import com.mapbox.geojson.Point;
+import com.mapbox.sample.BuildConfig;
+
+import java.util.Arrays;
+import java.util.List;
+import java.util.stream.Collectors;
+
+import retrofit2.Call;
+import retrofit2.Callback;
+import retrofit2.Response;
+
+public class BasicV6BatchGeocoding {
+
+  private static List<V6RequestOptions> requestOptions() {
+    final V6ForwardGeocodingRequestOptions forwardOptions = V6ForwardGeocodingRequestOptions
+      .builder("1600 Pennsylvania Avenue NW, Washington, DC 20500, United States")
+      .types(V6FeatureType.ADDRESS)
+      .limit(1)
+      .boundingBox(BoundingBox.fromLngLats(-80, 35, -70, 40))
+      .build();
+
+    final V6StructuredInputQuery structuredInputQuery = V6StructuredInputQuery.builder()
+      .addressNumber("1600")
+      .street("Pennsylvania Avenue NW")
+      .postcode("20500")
+      .place("Washington, DC")
+      .build();
+
+    final V6ForwardGeocodingRequestOptions structuredInputOptions = V6ForwardGeocodingRequestOptions
+      .builder(structuredInputQuery)
+      .country("us")
+      .build();
+
+    final V6ReverseGeocodingRequestOptions reverseOptions = V6ReverseGeocodingRequestOptions
+      .builder(Point.fromLngLat(-73.986136, 40.748895))
+      .types(V6FeatureType.ADDRESS)
+      .build();
+
+    return Arrays.asList(forwardOptions, structuredInputOptions, reverseOptions);
+  }
+
+  public static void main(String[] args) {
+    final MapboxV6BatchGeocoding geocoding = MapboxV6BatchGeocoding
+      .builder(
+        BuildConfig.MAPBOX_ACCESS_TOKEN,
+        requestOptions()
+      )
+      .build();
+
+    geocoding.enqueueCall(new Callback<V6BatchResponse>() {
+      @Override
+      public void onResponse(Call<V6BatchResponse> call, Response<V6BatchResponse> response) {
+        System.out.println("Response code: " + response.code());
+        System.out.println("Response message: " + response.message());
+
+        final V6BatchResponse body = response.body();
+        if (body == null) {
+          System.out.println("Response body is null");
+          return;
+        }
+
+        System.out.println("Number of responses: " + body.responses().size());
+
+        for (V6Response v6Response : body.responses()) {
+          System.out.println("Number of results: " + v6Response.features().size());
+
+          final String results = v6Response.features().stream()
+            .map(V6Feature::toString)
+            .collect(Collectors.joining(", \n"));
+
+          System.out.println("Features: " + results);
+        }
+      }
+
+      @Override
+      public void onFailure(Call<V6BatchResponse> call, Throwable t) {
+        System.out.println(t);
+      }
+    });
+  }
+}

samples/src/main/java/com/mapbox/samples/BasicV6ForwardGeocoding.java

@@ -0,0 +1,52 @@
+package com.mapbox.samples;
+
+import com.mapbox.api.geocoding.v6.MapboxV6Geocoding;
+import com.mapbox.api.geocoding.v6.V6ForwardGeocodingRequestOptions;
+import com.mapbox.api.geocoding.v6.models.V6Response;
+import com.mapbox.api.geocoding.v6.models.V6Feature;
+import com.mapbox.api.geocoding.v6.models.V6FeatureType;
+import com.mapbox.sample.BuildConfig;
+
+import java.util.stream.Collectors;
+
+import retrofit2.Call;
+import retrofit2.Callback;
+import retrofit2.Response;
+
+public class BasicV6ForwardGeocoding {
+
+  public static void main(String[] args) {
+    final V6ForwardGeocodingRequestOptions requestOptions = V6ForwardGeocodingRequestOptions
+      .builder("740 15th St NW, Washington, DC 20005")
+      .types(V6FeatureType.ADDRESS)
+      .build();
+
+    final MapboxV6Geocoding geocoding = MapboxV6Geocoding
+      .builder(BuildConfig.MAPBOX_ACCESS_TOKEN, requestOptions)
+      .build();
+
+    geocoding.enqueueCall(new Callback<V6Response>() {
+      @Override
+      public void onResponse(Call<V6Response> call, Response<V6Response> response) {
+        final V6Response body = response.body();
+        if (body == null) {
+          System.out.println("Response body is null");
+          return;
+        }
+
+        System.out.println("Number of results: " + body.features().size());
+
+        final String results = body.features().stream()
+            .map(V6Feature::toString)
+            .collect(Collectors.joining(", \n"));
+
+        System.out.println("Features: " + results);
+      }
+
+      @Override
+      public void onFailure(Call<V6Response> call, Throwable t) {
+        System.out.println(t);
+      }
+    });
+  }
+}

samples/src/main/java/com/mapbox/samples/BasicV6ReverseGeocoding.java

@@ -0,0 +1,51 @@
+package com.mapbox.samples;
+
+import com.mapbox.api.geocoding.v6.MapboxV6Geocoding;
+import com.mapbox.api.geocoding.v6.models.V6Feature;
+import com.mapbox.api.geocoding.v6.models.V6Response;
+import com.mapbox.api.geocoding.v6.V6ReverseGeocodingRequestOptions;
+import com.mapbox.geojson.Point;
+import com.mapbox.sample.BuildConfig;
+
+import java.util.stream.Collectors;
+
+import retrofit2.Call;
+import retrofit2.Callback;
+import retrofit2.Response;
+
+public class BasicV6ReverseGeocoding {
+
+  public static void main(String[] args) {
+    final V6ReverseGeocodingRequestOptions requestOptions = V6ReverseGeocodingRequestOptions
+      .builder(Point.fromLngLat(-77.03397315668123, 38.89991317162873))
+      .build();
+
+    final MapboxV6Geocoding geocoding = MapboxV6Geocoding
+      .builder(BuildConfig.MAPBOX_ACCESS_TOKEN, requestOptions)
+      .build();
+
+    geocoding.enqueueCall(new Callback<V6Response>() {
+      @Override
+      public void onResponse(Call<V6Response> call, Response<V6Response> response) {
+        final V6Response body = response.body();
+        if (body == null) {
+          System.out.println("Response body is null");
+          return;
+        }
+
+        System.out.println("Number of results: " + body.features().size());
+
+        final String results = body.features().stream()
+            .map(V6Feature::toString)
+            .collect(Collectors.joining(", \n"));
+
+        System.out.println("Features: " + results);
+      }
+
+      @Override
+      public void onFailure(Call<V6Response> call, Throwable t) {
+        System.out.println(t);
+      }
+    });
+  }
+}

samples/src/main/java/com/mapbox/samples/BasicV6StructuredInputForwardGeocoding.java

@@ -0,0 +1,62 @@
+package com.mapbox.samples;
+
+import com.mapbox.api.geocoding.v6.V6StructuredInputQuery;
+import com.mapbox.api.geocoding.v6.MapboxV6Geocoding;
+import com.mapbox.api.geocoding.v6.V6ForwardGeocodingRequestOptions;
+import com.mapbox.api.geocoding.v6.models.V6Feature;
+import com.mapbox.api.geocoding.v6.models.V6FeatureType;
+import com.mapbox.api.geocoding.v6.models.V6Response;
+import com.mapbox.sample.BuildConfig;
+
+import java.util.stream.Collectors;
+
+import retrofit2.Call;
+import retrofit2.Callback;
+import retrofit2.Response;
+
+public class BasicV6StructuredInputForwardGeocoding {
+
+  public static void main(String[] args) {
+    final V6StructuredInputQuery query = V6StructuredInputQuery.builder()
+      .addressNumber("740")
+      .street("15th St")
+      .place("Washington")
+      .postcode("20005")
+      .build();
+
+    final V6ForwardGeocodingRequestOptions requestOptions = V6ForwardGeocodingRequestOptions
+      .builder(query)
+      .country("United States")
+      .types(V6FeatureType.ADDRESS)
+      .autocomplete(false)
+      .build();
+
+    final MapboxV6Geocoding geocoding = MapboxV6Geocoding
+      .builder(BuildConfig.MAPBOX_ACCESS_TOKEN, requestOptions)
+      .build();
+
+    geocoding.enqueueCall(new Callback<V6Response>() {
+      @Override
+      public void onResponse(Call<V6Response> call, Response<V6Response> response) {
+        final V6Response body = response.body();
+        if (body == null) {
+          System.out.println("Response body is null");
+          return;
+        }
+
+        System.out.println("Number of results: " + body.features().size());
+
+        final String results = body.features().stream()
+            .map(V6Feature::toString)
+            .collect(Collectors.joining(", \n"));
+
+        System.out.println("Features: " + results);
+      }
+
+      @Override
+      public void onFailure(Call<V6Response> call, Throwable t) {
+        System.out.println(t);
+      }
+    });
+  }
+}

services-geocoding/src/main/java/com/mapbox/api/geocoding/v6/MapboxV6BaseGeocoding.java

@@ -0,0 +1,66 @@
+package com.mapbox.api.geocoding.v6;
+
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+
+import com.mapbox.core.MapboxService;
+
+/**
+ * Base class for entry points to Mapbox V6 geocoding: forward geocoding, reverse geocoding
+ * and batch geocoding. See derived classes for more information.
+ * @param <T> response type.
+ */
+public abstract class MapboxV6BaseGeocoding<T> extends MapboxService<T, V6GeocodingService> {
+
+  @NonNull
+  protected abstract String accessToken();
+
+  @Nullable
+  protected abstract Boolean permanent();
+
+  @Nullable
+  protected abstract String clientAppName();
+
+  @NonNull
+  @Override
+  protected abstract String baseUrl();
+
+  protected MapboxV6BaseGeocoding() {
+    super(V6GeocodingService.class);
+  }
+
+  /**
+   * Base class for Mapbox V6 Geocoding Builders.
+   * @param <T> type of Builder
+   */
+  public abstract static class BaseBuilder<T> {
+
+    protected abstract T accessToken(@NonNull String accessToken);
+
+    /**
+     * Specify whether you intend to store the results of the query. Backend default is false.
+     *
+     * @param permanent specify whether you intend to store the results
+     * @return this builder for chaining options together
+     *
+     * @see <a href="https://docs.mapbox.com/api/search/geocoding/#storing-geocoding-results">Storing Geocoding Results</a>
+     */
+    public abstract T permanent(@NonNull Boolean permanent);
+
+    /**
+     * Base package name or other simple string identifier. Used inside the calls user agent header.
+     *
+     * @param clientAppName base package name or other simple string identifier
+     * @return this builder for chaining options together
+     */
+    public abstract T clientAppName(@NonNull String clientAppName);
+
+    /**
+     * Optionally change the APIs base URL to something other then the default Mapbox one.
+     *
+     * @param baseUrl base url used as end point
+     * @return this builder for chaining options together
+     */
+    public abstract T baseUrl(@NonNull String baseUrl);
+  }
+}