Eric/add custom parameter (#58)

* Added ETAG Header for the US Address Enrichment API

* - Added Custom Parameter to All APIs
 - Added county_source Parameter to the US Street Address API

* Resolved consistency issues in examples

* Restored US Street Single Address Example

* Restored Invalid Match Type in US Street Example

examples/international_autocomplete_example.rb

@@ -32,6 +32,8 @@ def run
     lookup.country = "FRA"
     lookup.locality = "Paris"
 
+    # lookup.add_custom_parameter('parameter', 'value')
+
     suggestions = client.send(lookup) # The client will also return the suggestions directly
 
     puts

examples/international_example.rb

@@ -38,6 +38,8 @@ def run
     lookup.country = 'Brazil'
     lookup.postal_code = '02516-050'
 
+    # lookup.add_custom_parameter('parameter', 'value')
+
     candidates = client.send_lookup(lookup) # The candidates are also stored in the lookup's 'result' field.
 
     first_candidate = candidates[0]

examples/us_autocomplete_pro_example.rb

@@ -39,6 +39,8 @@ def run
     lookup.prefer_ratio = 3
     lookup.source = "all"
 
+    # lookup.add_custom_parameter('parameter', 'value')
+
     suggestions = client.send(lookup) # The client will also return the suggestions directly
 
     puts

examples/us_enrichment_example.rb

@@ -33,7 +33,9 @@ def run
     lookup.city = "Somerville"
     lookup.state = "NJ"
     lookup.zipcode = "08876"
-    #lookup.etag = "AUBAGDQDAIGQYCYC"
+    # lookup.etag = "AUBAGDQDAIGQYCYC"
+
+    # lookup.add_custom_parameter('parameter', 'value')
 
     # Or, create a freeform lookup to search using a single line address
     freeform_lookup = SmartyStreets::USEnrichment::Lookup.new

examples/us_extract_example.rb

@@ -37,6 +37,8 @@ def run
     lookup.addresses_per_line = 2
     lookup.match =  SmartyStreets::USStreet::MatchType::ENHANCED
 
+    # lookup.add_custom_parameter('parameter', 'value')
+
     result = client.send(lookup)
 
     metadata = result.metadata

examples/us_reverse_geo_example.rb

@@ -29,6 +29,8 @@ def run
 
     lookup = Lookup.new(40.111111, -111.111111)
 
+    # lookup.add_custom_parameter('parameter', 'value')
+
     response = client.send(lookup)
     result = response.results[0]
 

examples/us_street_multiple_address_example.rb

@@ -44,6 +44,8 @@ def run
                                       # this will always return at least one result even if the address is invalid.
                                       # Refer to the documentation for additional Match Strategy options.
 
+    # batch[0].add_custom_parameter('parameter', 'value')
+
     batch.add(Lookup.new('1 Rosedale, Baltimore, Maryland')) # Freeform addresses work too.
     batch[1].candidates = 10 # Allows up to ten possible matches to be returned (default is 1).
 

examples/us_street_single_address_example.rb

@@ -40,11 +40,14 @@ def run
     lookup.state = 'CA'
     lookup.zipcode = '21229'
     lookup.candidates = 3
+    lookup.county_source = SmartyStreets::USStreet::CountySource::GEOGRAPHIC
     lookup.match = SmartyStreets::USStreet::MatchType::INVALID
                                     # "invalid" is the most permissive match,
                                     # this will always return at least one result even if the address is invalid.
                                     # Refer to the documentation for additional Match Strategy options.
 
+    # lookup.add_custom_parameter('parameter', 'value')
+
     begin
       client.send_lookup(lookup)
     rescue SmartyStreets::SmartyError => err

examples/us_zipcode_multiple_lookup_example.rb

@@ -29,6 +29,8 @@ def run
     batch[0].input_id = '01189998819991197253' # Optional ID from your system
     batch[0].zipcode = '12345' # A Lookup may have a ZIP Code, city and state, or city, state, and ZIP Code
 
+    # batch[0].add_custom_parameter('parameter', 'value')
+
     batch.add(Lookup.new)
     batch[1].city = 'Phoenix'
     batch[1].state = 'Arizona'

examples/us_zipcode_single_lookup_example.rb

@@ -27,6 +27,8 @@ def run
     lookup.state = 'California'
     lookup.zipcode = '94043'
 
+    # lookup.add_custom_parameter('parameter', 'value')
+
     begin
       client.send_lookup(lookup)
     rescue SmartyStreets::SmartyError => err

lib/smartystreets_ruby_sdk/international_autocomplete/client.rb

@@ -42,6 +42,10 @@ def build_request(lookup)
         add_parameter(request, 'include_only_locality', lookup.locality)
         add_parameter(request, 'include_only_postal_code', lookup.postal_code)
 
+        for key in lookup.custom_param_hash.keys do
+          add_parameter(request, key, lookup.custom_param_hash[key])
+        end
+
         request
       end
 

lib/smartystreets_ruby_sdk/international_autocomplete/lookup.rb

@@ -6,16 +6,21 @@ module InternationalAutocomplete
     # of the lookup after it comes back from the API.
     class Lookup < JSONAble
 
-      attr_accessor :result, :search, :address_id, :country, :max_results, :locality, :postal_code
+      attr_accessor :result, :search, :address_id, :country, :max_results, :locality, :postal_code, :custom_param_hash
 
-      def initialize(search = nil, address_id = nil, country = nil, max_results = nil, locality = nil, postal_code = nil)
+      def initialize(search = nil, address_id = nil, country = nil, max_results = nil, locality = nil, postal_code = nil, custom_param_hash = nil)
         @result = []
         @search = search
         @address_id = address_id
         @country = country
         @max_results = max_results
         @locality = locality
         @postal_code = postal_code
+        @custom_param_hash = {}
+      end
+
+      def add_custom_parameter(parameter, value)
+        @custom_param_hash[parameter] = value
       end
     end
   end

lib/smartystreets_ruby_sdk/international_street/client.rb

@@ -54,6 +54,10 @@ def build_request(lookup)
         add_parameter(request, 'administrative_area', lookup.administrative_area)
         add_parameter(request, 'postal_code', lookup.postal_code)
 
+        for key in lookup.custom_param_hash.keys do
+          add_parameter(request, key, lookup.custom_param_hash[key])
+        end
+
         request
       end
 

lib/smartystreets_ruby_sdk/international_street/lookup.rb

@@ -15,7 +15,7 @@ module InternationalStreet
     class Lookup
 
       attr_accessor :input_id, :freeform, :locality, :postal_code, :address3, :address2, :inputId, :address1,
-                    :geocode, :administrative_area, :country, :organization, :language, :address4, :result
+                    :geocode, :administrative_area, :country, :organization, :language, :address4, :result, :custom_param_hash
 
       def initialize(freeform=nil, country=nil)
         @result = []
@@ -33,6 +33,11 @@ def initialize(freeform=nil, country=nil)
         @locality = nil
         @administrative_area = nil
         @postal_code = nil
+        @custom_param_hash = {}
+      end
+
+      def add_custom_parameter(parameter, value)
+        @custom_param_hash[parameter] = value
       end
 
       def missing_country

lib/smartystreets_ruby_sdk/us_autocomplete_pro/client.rb

@@ -51,6 +51,10 @@ def build_request(lookup)
         end
         add_parameter(request, 'selected', lookup.selected)
 
+        for key in lookup.custom_param_hash.keys do
+          add_parameter(request, key, lookup.custom_param_hash[key])
+        end
+
         request
       end
 

lib/smartystreets_ruby_sdk/us_autocomplete_pro/lookup.rb

@@ -10,11 +10,11 @@ class Lookup < JSONAble
 
       attr_accessor :result, :search, :max_results, :city_filter, :state_filter, :zip_filter,
                     :exclude_states, :prefer_cities, :prefer_states, :prefer_zip_codes, :prefer_ratio,
-                    :prefer_geolocation, :selected, :source
+                    :prefer_geolocation, :selected, :source, :custom_param_hash
 
       def initialize(search=nil, max_results=nil, city_filter=nil, state_filter=nil, zip_filter=nil,
                      exclude_states=nil, prefer_cities=nil, prefer_states=nil, prefer_zips=nil, prefer_ratio=nil,
-                     prefer_geolocation=nil, selected=nil, source=nil)
+                     prefer_geolocation=nil, selected=nil, source=nil, custom_param_hash=nil)
         @result = []
         @search = search
         @max_results = max_results
@@ -29,6 +29,11 @@ def initialize(search=nil, max_results=nil, city_filter=nil, state_filter=nil, z
         @prefer_geolocation = prefer_geolocation
         @selected = selected
         @source = source
+        @custom_param_hash = {}
+      end
+
+      def add_custom_parameter(parameter, value)
+        @custom_param_hash[parameter] = value
       end
 
       def add_city_filter(city)

lib/smartystreets_ruby_sdk/us_enrichment/client.rb

@@ -105,6 +105,9 @@ def __send(lookup)
                         smarty_request.url_components = '/' + lookup.smarty_key + '/' + lookup.data_set + '/' + lookup.data_sub_set
                     end
                 end
+                for key in lookup.custom_param_hash.keys do
+                    add_parameter(smarty_request, key, lookup.custom_param_hash[key])
+                end
 
 
                 response = @sender.send(smarty_request)

lib/smartystreets_ruby_sdk/us_enrichment/lookup.rb

@@ -2,9 +2,9 @@
 module SmartyStreets
   module USEnrichment
     class Lookup < JSONAble
-      attr_accessor :smarty_key, :data_set, :data_sub_set, :freeform, :street, :city, :state, :zipcode, :etag
+      attr_accessor :smarty_key, :data_set, :data_sub_set, :freeform, :street, :city, :state, :zipcode, :etag, :custom_param_hash
 
-      def initialize(smarty_key=nil, data_set=nil, data_sub_set=nil, freeform=nil, street=nil, city=nil, state=nil, zipcode=nil, etag=nil)
+      def initialize(smarty_key=nil, data_set=nil, data_sub_set=nil, freeform=nil, street=nil, city=nil, state=nil, zipcode=nil, etag=nil, custom_param_hash=nil)
         @smarty_key = smarty_key
         @data_set = data_set
         @data_sub_set = data_sub_set
@@ -14,6 +14,11 @@ def initialize(smarty_key=nil, data_set=nil, data_sub_set=nil, freeform=nil, str
         @state = state
         @zipcode = zipcode
         @etag = etag
+        @custom_param_hash = {}
+      end
+
+      def add_custom_parameter(parameter, value)
+        @custom_param_hash[parameter] = value
       end
     end
   end

lib/smartystreets_ruby_sdk/us_extract/client.rb

@@ -41,6 +41,10 @@ def build_request(lookup)
           add_parameter(request, 'match', lookup.match)
         end
 
+        for key in lookup.custom_param_hash.keys do
+          add_parameter(request, key, lookup.custom_param_hash[key])
+        end
+
         request
       end
 

lib/smartystreets_ruby_sdk/us_extract/lookup.rb

@@ -7,16 +7,21 @@ module USExtract
     #
     # See "https://smartystreets.com/docs/cloud/us-extract-api#http-request-input-fields"
     class Lookup < JSONAble
-      attr_accessor :text, :result, :aggressive, :addresses_per_line, :html, :addresses_have_line_breaks, :match
+      attr_accessor :text, :result, :aggressive, :addresses_per_line, :html, :addresses_have_line_breaks, :match, :custom_param_hash
 
-      def initialize(text=nil, html=nil, aggressive=nil, addresses_have_line_breaks=nil, addresses_per_line=nil, match=nil)
+      def initialize(text=nil, html=nil, aggressive=nil, addresses_have_line_breaks=nil, addresses_per_line=nil, match=nil, custom_param_hash=nil)
         @text = text
         @html = html
         @aggressive = aggressive
         @addresses_have_line_breaks = addresses_have_line_breaks
         @addresses_per_line = addresses_per_line
         @match = match
         @result = nil
+        @custom_param_hash = {}
+      end
+
+      def add_custom_parameter(parameter, value)
+        @custom_param_hash[parameter] = value
       end
     end
   end

lib/smartystreets_ruby_sdk/us_reverse_geo/client.rb

@@ -28,6 +28,10 @@ def build_request(lookup)
         add_parameter(request, 'longitude', lookup.longitude)
         add_parameter(request, 'source', lookup.source)
 
+        for key in lookup.custom_param_hash.keys do
+          add_parameter(request, key, lookup.custom_param_hash[key])
+        end
+
         request
       end
 

lib/smartystreets_ruby_sdk/us_reverse_geo/lookup.rb

@@ -10,12 +10,17 @@ module USReverseGeo
 
     class Lookup
 
-      attr_accessor :latitude, :longitude, :source, :response
+      attr_accessor :latitude, :longitude, :source, :response, :custom_param_hash
 
-      def initialize(latitude, longitude, source)
+      def initialize(latitude, longitude, source=nil, custom_param_hash=nil)
         @latitude = sprintf('%.8f', latitude)
         @longitude = sprintf('%.8f', longitude)
         @source = source
+        @custom_param_hash = {}
+      end
+
+      def add_custom_parameter(parameter, value)
+        @custom_param_hash[parameter] = value
       end
     end
   end

lib/smartystreets_ruby_sdk/us_street/client.rb

@@ -62,6 +62,12 @@ def remap_keys(obj)
           converted_lookup['match'] = lookup.match
           converted_lookup['candidates'] = lookup.candidates
           converted_lookup['format'] = lookup.format
+          converted_lookup['county_source'] = lookup.county_source
+
+          for key in lookup.custom_param_hash.keys do
+            converted_lookup[key] = lookup.custom_param_hash[key]
+          end
+
           converted_obj.push(converted_lookup)
         end
         converted_obj

lib/smartystreets_ruby_sdk/us_street/lookup.rb

@@ -9,10 +9,10 @@ module USStreet
     # @match:: Must be set to 'strict', 'enhanced', or 'invalid'. Constants for these are in match_type.rb
     class Lookup < JSONAble
       attr_accessor :input_id, :street, :street2, :secondary, :city, :state, :zipcode, :lastline, :addressee, :urbanization,
-                    :match, :candidates, :format, :result
+                    :match, :candidates, :format, :county_source, :custom_param_hash, :result
 
       def initialize(street=nil, street2=nil, secondary=nil, city=nil, state=nil, zipcode=nil, lastline=nil,
-                     addressee=nil, urbanization=nil, match=nil, candidates=0, input_id=nil, format=nil)
+                     addressee=nil, urbanization=nil, match=nil, candidates=0, input_id=nil, county_source=nil, format=nil)
         @input_id = input_id
         @street = street
         @street2 = street2
@@ -26,8 +26,15 @@ def initialize(street=nil, street2=nil, secondary=nil, city=nil, state=nil, zipc
         @match = match
         @candidates = candidates
         @format = format
+        @county_source = county_source
+        @custom_param_hash = {}
         @result = []
       end
+
+      def add_custom_parameter(parameter, value)
+        @custom_param_hash[parameter] = value
+      end
+
     end
   end
 end

lib/smartystreets_ruby_sdk/us_street/match_type.rb

@@ -10,5 +10,10 @@ module OutputFormat
       DEFAULT = 'default'.freeze
       PROJECT_USA = 'project-usa'.freeze
     end
+
+    module CountySource
+      POSTAL = 'postal'.freeze
+      GEOGRAPHIC = 'geographic'.freeze
+    end
   end
 end

lib/smartystreets_ruby_sdk/us_zipcode/client.rb

@@ -58,6 +58,10 @@ def remap_keys(obj)
           add_field(converted_lookup, 'state', lookup.state)
           add_field(converted_lookup, 'zipcode', lookup.zipcode)
 
+          for key in lookup.custom_param_hash.keys do
+            add_field(converted_lookup, key, lookup.custom_param_hash[key])
+          end
+
           converted_obj.push(converted_lookup)
         end
 

lib/smartystreets_ruby_sdk/us_zipcode/lookup.rb

@@ -7,14 +7,19 @@ module USZipcode
     #
     #   See "https://smartystreets.com/docs/cloud/us-zipcode-api#http-request-input-fields"
     class Lookup < JSONAble
-      attr_accessor :result, :state, :zipcode, :input_id, :city
+      attr_accessor :result, :state, :zipcode, :input_id, :city, :custom_param_hash
 
-      def initialize(city=nil, state=nil, zipcode=nil, input_id=nil)
+      def initialize(city=nil, state=nil, zipcode=nil, input_id=nil, custom_param_hash=nil)
         @result = nil
         @input_id = input_id
         @city = city
         @state = state
         @zipcode = zipcode
+        @custom_param_hash = {}
+      end
+
+      def add_custom_parameter(parameter, value)
+        @custom_param_hash[parameter] = value
       end
     end
   end