Library and examples now implement US Autocomplete Pro API

src/main/java/com/smartystreets/api/ClientBuilder.java

@@ -20,6 +20,7 @@ public class ClientBuilder {
     private Map<String, Object> customHeaders;
     private final String INTERNATIONAL_STREET_API_URL = "https://international-street.api.smartystreets.com/verify";
     private final String US_AUTOCOMPLETE_API_URL = "https://us-autocomplete.api.smartystreets.com/suggest";
+    private final String US_AUTOCOMPLETE_API_PRO_URL = "https://us-autocomplete-pro.api.smartystreets.com/lookup";
     private final String US_EXTRACT_API_URL = "https://us-extract.api.smartystreets.com/";
     private final String US_STREET_API_URL = "https://us-street.api.smartystreets.com/street-address";
     private final String US_ZIP_CODE_API_URL = "https://us-zipcode.api.smartystreets.com/lookup";
@@ -128,6 +129,11 @@ public com.smartystreets.api.us_autocomplete.Client buildUsAutocompleteApiClient
         return new com.smartystreets.api.us_autocomplete.Client(this.buildSender(), this.serializer);
     }
 
+    public com.smartystreets.api.us_autocomplete_pro.Client buildUsAutocompleteProApiClient() {
+        this.ensureURLPrefixNotNull(this.US_AUTOCOMPLETE_API_PRO_URL);
+        return new com.smartystreets.api.us_autocomplete_pro.Client(this.buildSender(), this.serializer);
+    }
+
     public com.smartystreets.api.us_extract.Client buildUsExtractApiClient() {
         this.ensureURLPrefixNotNull(this.US_EXTRACT_API_URL);
         return new com.smartystreets.api.us_extract.Client(this.buildSender(), this.serializer);

src/main/java/com/smartystreets/api/us_autocomplete/GeolocateType.java → src/main/java/com/smartystreets/api/GeolocateType.java

@@ -1,4 +1,4 @@
-package com.smartystreets.api.us_autocomplete;
+package com.smartystreets.api;
 
 /**
  * This field corresponds to the <b>geolocate</b> and <b>geolocate_precision</b> fields in the US Autocomplete API.

src/main/java/com/smartystreets/api/us_autocomplete/Lookup.java

@@ -1,6 +1,7 @@
 package com.smartystreets.api.us_autocomplete;
 
 import java.util.ArrayList;
+import com.smartystreets.api.GeolocateType;
 
 /**
  * In addition to holding all of the input data for this lookup, this class also<br>

src/main/java/com/smartystreets/api/us_autocomplete_pro/Client.java

@@ -0,0 +1,79 @@
+package com.smartystreets.api.us_autocomplete_pro;
+
+
+import com.smartystreets.api.*;
+import com.smartystreets.api.exceptions.SmartyException;
+
+import java.io.IOException;
+import java.util.ArrayList;
+
+/**
+ * This client sends lookups to the SmartyStreets US Autocomplete API, <br>
+ *     and attaches the results to the appropriate Lookup objects.
+ */
+public class Client {
+    private final Sender sender;
+    private final Serializer serializer;
+
+    public Client(Sender sender, Serializer serializer) {
+        this.sender = sender;
+        this.serializer = serializer;
+    }
+
+    public Suggestion[] send(Lookup lookup) throws SmartyException, IOException {
+        if (lookup == null || lookup.getPrefix() == null || lookup.getPrefix().length() == 0)
+            throw new SmartyException("Send() must be passed a Lookup with the prefix field set.");
+
+        Request request = this.buildRequest(lookup);
+
+        Response response = this.sender.send(request);
+
+        Result result = this.serializer.deserialize(response.getPayload(), Result.class);
+        Suggestion[] suggestions = result.getSuggestions();
+        lookup.setResult(suggestions);
+
+        return suggestions;
+    }
+
+    private Request buildRequest(Lookup lookup) {
+        Request request = new Request();
+
+        request.putParameter("prefix", lookup.getPrefix());
+        request.putParameter("suggestions", lookup.getMaxSuggestionsStringIfSet());
+        request.putParameter("city_filter", this.buildFilterString(lookup.getCityFilter()));
+        request.putParameter("state_filter", this.buildFilterString(lookup.getStateFilter()));
+        request.putParameter("prefer", this.buildPreferString(lookup.getPrefer()));
+        request.putParameter("prefer_ratio", lookup.getPreferRatioStringIfSet());
+        if (lookup.getGeolocateType() != GeolocateType.NONE) {
+            request.putParameter("geolocate", "true");
+            request.putParameter("geolocate_precision", lookup.getGeolocateType().getName());
+        }
+        else request.putParameter("geolocate", "false");
+
+        return request;
+    }
+
+    private String buildPreferString(ArrayList<String> list) {
+        return buildStringFromList(list, ";");
+    }
+
+    private String buildFilterString(ArrayList<String> list) {
+        return buildStringFromList(list, ",");
+    }
+
+    private String buildStringFromList(ArrayList<String> list, String separator) {
+        if (list.isEmpty())
+            return null;
+
+        String filterList = "";
+
+        for (String item : list) {
+            filterList += (item + separator);
+        }
+
+        if (filterList.endsWith(separator))
+            filterList = filterList.substring(0, filterList.length()-1);
+
+        return filterList;
+    }
+}

src/main/java/com/smartystreets/api/us_autocomplete_pro/Lookup.java

@@ -0,0 +1,186 @@
+package com.smartystreets.api.us_autocomplete_pro;
+
+import java.lang.reflect.Array;
+import java.util.ArrayList;
+import com.smartystreets.api.GeolocateType;
+
+/**
+ * In addition to holding all of the input data for this lookup, this class also<br>
+ *     will contain the result of the lookup after it comes back from the API.
+ *     @see "https://smartystreets.com/docs/cloud/us-autocomplete-api#http-request-input-fields"
+ */
+public class Lookup {
+    final double PREFER_RATIO_DEFAULT = 1/3.0;
+    final int MAX_SUGGESTIONS_DEFAULT = 10;
+
+    //region [ Fields ]
+
+    private Suggestion[] result;
+    private String search;
+    private int maxSuggestions;
+    private ArrayList<String> cityFilter;
+    private ArrayList<String> stateFilter;
+    private ArrayList<String> zipcodeFilter;
+    private ArrayList<String> preferCity;
+    private ArrayList<String> preferState;
+    private ArrayList<String> preferZipcode;
+    private double preferRatio;
+    private GeolocateType preferGeolocation;
+
+    //endregion
+
+    //region [ Constructors ]
+
+    /**
+     * If you use this constructor, don't forget to set the <b>prefix</b>. It is required.
+     */
+    public Lookup() {
+        this.maxSuggestions = this.MAX_SUGGESTIONS_DEFAULT;
+        this.preferGeolocation = GeolocateType.CITY;
+        this.cityFilter = new ArrayList<>();
+        this.stateFilter = new ArrayList<>();
+        this.zipcodeFilter = new ArrayList<>();
+        this.preferCity = new ArrayList<>();
+        this.preferState = new ArrayList<>();
+        this.preferZipcode = new ArrayList<>();
+        this.preferRatio = this.PREFER_RATIO_DEFAULT;
+    }
+
+    /**
+     * @param search The beginning of an address
+     */
+    public Lookup(String search) {
+        this();
+        this.search = search;
+    }
+
+    //endregion
+
+    //region [ Getters ]
+
+    public Suggestion[] getResult() {
+        return this.result;
+    }
+
+    public Suggestion getResult(int index) {
+        return this.result[index];
+    }
+
+    public String getSearch() {
+        return this.search;
+    }
+
+    public ArrayList<String> getCityFilter() {
+        return this.cityFilter;
+    }
+
+    public ArrayList<String> getStateFilter() {
+        return this.stateFilter;
+    }
+
+    public ArrayList<String> getPreferCity() {
+        return this.preferCity;
+    }
+
+    public ArrayList<String> getPreferState() { return this.preferState; }
+
+    public ArrayList<String> getPreferZipcode() { return this.preferZipcode; }
+
+    public double getPreferRatio() {
+        return this.preferRatio;
+    }
+
+    String getPreferRatioStringIfSet() {
+        if (this.preferRatio == this.PREFER_RATIO_DEFAULT)
+            return null;
+        return Double.toString(this.preferRatio);
+    }
+
+    public GeolocateType getGeolocateType() {
+        return preferGeolocation;
+    }
+
+    public int getMaxSuggestions() {
+        return maxSuggestions;
+    }
+
+    String getMaxSuggestionsStringIfSet() {
+        if (this.maxSuggestions == this.MAX_SUGGESTIONS_DEFAULT)
+            return null;
+        return Integer.toString(this.maxSuggestions);
+    }
+
+    //endregion
+
+    //region [ Setters ]
+
+    public void setResult(Suggestion[] result) {
+        this.result = result;
+    }
+
+    public void setSearch(String search) {
+        this.search = search;
+    }
+
+    public void setCityFilter(ArrayList<String> cityFilter) {
+        this.cityFilter = cityFilter;
+    }
+
+    public void setStateFilter(ArrayList<String> stateFilter) {
+        this.stateFilter = stateFilter;
+    }
+
+    public void setZipcodeFilter(ArrayList<String> zipcodeFilter) { this.zipcodeFilter = zipcodeFilter ;}
+
+    public void setPreferCity(ArrayList<String> cities) {
+        this.preferCity = cities;
+    }
+
+    public void setPreferState(ArrayList<String> states) { this.preferState = states; }
+
+    public void setPreferZipcode(ArrayList<String> zipcodes) { this.preferZipcode = zipcodes; }
+
+    /***
+     * Sets the percentage of suggestions that are to be from preferred cities/states.
+     * @param preferRatio A decimal value, range [0, 1]. Default is 0.333333333.
+     * @see "https://smartystreets.com/docs/cloud/us-autocomplete-api#preference"
+     */
+    public void setPreferRatio(double preferRatio) {
+        this.preferRatio = preferRatio;
+    }
+
+    public void setGeolocateType(GeolocateType geolocateType) {
+        this.preferGeolocation = geolocateType;
+    }
+
+    /***
+     * Sets the maximum number of suggestions to return.
+     * @param maxSuggestions A positive integer range [1, 10]. Default is 10.
+     * @throws IllegalArgumentException
+     */
+    public void setMaxSuggestions(int maxSuggestions) throws IllegalArgumentException{
+        if (maxSuggestions > 0 && maxSuggestions <= this.MAX_SUGGESTIONS_DEFAULT) {
+            this.maxSuggestions = maxSuggestions;
+        } else {
+            throw new IllegalArgumentException("Max suggestions must be a positive integer no larger than 10.");
+        }
+    }
+
+    public void addCityFilter(String city) {
+        this.cityFilter.add(city);
+    }
+
+    public void addStateFilter(String stateAbbreviation) {
+        this.stateFilter.add(stateAbbreviation);
+    }
+
+    public void addPreferCity(String city) {
+        this.preferCity.add(city);
+    }
+
+    public void addPreferState(String state) { this.preferState.add(state); }
+
+    public void addPreferZipcode(String zipcode) { this.preferZipcode.add(zipcode); }
+
+    //endregion
+}

src/main/java/com/smartystreets/api/us_autocomplete_pro/Result.java

@@ -0,0 +1,17 @@
+package com.smartystreets.api.us_autocomplete_pro;
+
+
+import com.google.api.client.util.Key;
+
+public class Result {
+    @Key("suggestions")
+    private Suggestion[] suggestions;
+
+    public Suggestion[] getSuggestions() {
+        return this.suggestions;
+    }
+
+    public Suggestion getSuggestion(int index) {
+        return this.suggestions[index];
+    }
+}

src/main/java/com/smartystreets/api/us_autocomplete_pro/Suggestion.java

@@ -0,0 +1,52 @@
+package com.smartystreets.api.us_autocomplete_pro;
+
+import com.google.api.client.util.Key;
+
+/**
+ * @see "https://smartystreets.com/docs/cloud/us-autocomplete-api#http-response"
+ */
+public class Suggestion {
+    //region [ Fields ]
+
+    @Key("street_line")
+    private String streetLine;
+
+    @Key("secondary")
+    private String secondary;
+
+    @Key("city")
+    private String city;
+
+    @Key("state")
+    private String state;
+
+    @Key("zipcode")
+    private String zipcode;
+
+    @Key("entries")
+    private Integer entries;
+
+    //region [ Fields ]
+
+    //region [ Getters ]
+
+    public String getStreetLine() {
+        return streetLine;
+    }
+
+    public String getSecondary() { return secondary; }
+
+    public String getCity() {
+        return city;
+    }
+
+    public String getState() {
+        return state;
+    }
+
+    public String getZipcode() { return zipcode; }
+
+    public Integer getEntries() { return entries; }
+
+    //endregion
+}