smartystreets_ruby_sdk 9.0.0 → 9.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f80a7994c3b9e2b9c0936875503a6fe6751db574e64861014ead029f5e1079e
-  data.tar.gz: d488f5c6698c089bc147d562793d67e5478b70c23da9d76e8607fe03111b0a93
+  metadata.gz: f033c107bfea0fb806b080faed0a58d7d9e2a062acc88f74b162fd0b2f4db73a
+  data.tar.gz: eb2ec5974ad3143e1abd197daea71fb6ac817eaf9bc2b4e84a1cd34d2c621012
 SHA512:
-  metadata.gz: 739c0edcc1fc7e0a6d4cff83ec12adb0f2f146518e211fe981988d2d4dc18921c16866e911de63612df5e3638a72835bdf6f74a69a8b218c459211941a257c3b
-  data.tar.gz: 1f8de619ff3655c99a97d7acb5a3c95d892451c7aab832dd8e0cc88c32ecb12a8b1d6e8237cb3f9032ca7fee8573c43cbdcf805313f10b3c67de8fab42317484
+  metadata.gz: 4d6cdd50b585f1bec44a2ca6cf8391613774c9bea95f6537343f9565f884fd56a976cc91ebb089c9d426b3f762e0fb4bf23ec3c2e0084bbadc3179234ab3108d
+  data.tar.gz: 2c45d8292d54cf45b2f1add26eecc7ba8de652f4668d448fcf404b9371910ba9e9638e5804fae06d8decd3e70dd1dbb95abe67c1e7ada889076cb4fe71adc90f

data/CLAUDE.md

@@ -58,7 +58,7 @@ URLPrefixSender → CustomQuerySender → LicenseSender → RetrySender → Sign
 
 ### Supported APIs
 
-- US Street, US ZipCode, US Autocomplete Pro, US Extract, US Reverse Geo, US Enrichment
+- US Street, US ZipCode, US Autocomplete, US Autocomplete Pro, US Extract, US Reverse Geo, US Enrichment
 - International Street, International Autocomplete, International Postal Code
 
 ### Test Structure

data/Makefile

@@ -33,6 +33,9 @@ international_postal_code_api:
 international_street_api:
 	cd examples && ruby international_example.rb
 
+us_autocomplete_api:
+	cd examples && ruby us_autocomplete_example.rb
+
 us_autocomplete_pro_api:
 	cd examples && ruby us_autocomplete_pro_example.rb
 
@@ -54,6 +57,6 @@ us_street_match_strategy_api:
 us_zipcode_api:
 	cd examples && ruby us_zipcode_single_lookup_example.rb && ruby us_zipcode_multiple_lookup_example.rb
 
-examples: international_autocomplete_api international_postal_code_api international_street_api us_autocomplete_pro_api us_enrichment_api us_extract_api us_reverse_geo_api us_street_api us_zipcode_api
+examples: international_autocomplete_api international_postal_code_api international_street_api us_autocomplete_pro_api us_autocomplete_api us_enrichment_api us_extract_api us_reverse_geo_api us_street_api us_zipcode_api
 
-.PHONY: clean test dependencies package publish international_autocomplete_api international_postal_code_api international_street_api us_autocomplete_pro_api us_enrichment_api us_extract_api us_reverse_geo_api us_street_api us_street_match_strategy_api us_zipcode_api examples
+.PHONY: clean test dependencies package publish international_autocomplete_api international_postal_code_api international_street_api us_autocomplete_pro_api us_autocomplete_api us_enrichment_api us_extract_api us_reverse_geo_api us_street_api us_street_match_strategy_api us_zipcode_api examples

data/examples/us_autocomplete_example.rb

@@ -0,0 +1,69 @@
+require '../lib/smartystreets_ruby_sdk/shared_credentials'
+require '../lib/smartystreets_ruby_sdk/static_credentials'
+require '../lib/smartystreets_ruby_sdk/basic_auth_credentials'
+require '../lib/smartystreets_ruby_sdk/client_builder'
+require '../lib/smartystreets_ruby_sdk/us_autocomplete/lookup'
+require '../lib/smartystreets_ruby_sdk/us_autocomplete/source_type'
+
+# This example is for US Autocomplete (V2). It has the same name as a previous product
+# which has been deprecated since 2022, which we refer to as US Autocomplete Basic.
+# If you are still using US Autocomplete Basic, this SDK will not work.
+class USAutocompleteExample
+  Lookup = SmartyStreets::USAutocomplete::Lookup
+  SourceType = SmartyStreets::USAutocomplete::SourceType
+
+  def run
+    # key = 'Your SmartyStreets Auth Key here'
+    # referer = 'Your host name here'
+    # We recommend storing your secret keys in environment variables instead---it's safer!
+    # key = ENV['SMARTY_AUTH_WEB']
+    # referer = ENV['SMARTY_AUTH_REFERER']
+    # credentials = SmartyStreets::SharedCredentials.new(key, referer)
+
+    id = ENV['SMARTY_AUTH_ID']
+    token = ENV['SMARTY_AUTH_TOKEN']
+    credentials = SmartyStreets::BasicAuthCredentials.new(id, token)
+
+    client = SmartyStreets::ClientBuilder.new(credentials).build_us_autocomplete_api_client
+
+    # Documentation for input fields can be found at:
+    # https://www.smarty.com/docs/apis/us-autocomplete-v2/reference#http-request-input-fields
+
+    lookup = Lookup.new('1042 W Center')
+    lookup.add_city_filter('Denver,Aurora,CO')
+    lookup.add_city_filter('Orem,UT')
+    lookup.max_results = 5
+    lookup.prefer_ratio = 3
+    lookup.source = SourceType::ALL
+
+    # lookup.add_custom_parameter('parameter', 'value')
+
+    suggestions = client.send(lookup) # The client will also return the suggestions directly
+
+    puts
+    puts '*** Result with some filters ***'
+    puts
+
+    entry_id = nil
+    suggestions.each do |suggestion|
+      puts "#{suggestion.street_line} #{suggestion.city}, #{suggestion.state}"
+      entry_id = suggestion.entry_id if suggestion.entry_id && !suggestion.entry_id.empty?
+    end
+
+    # Expand the secondaries of a result that has an entry_id by passing it back as the selected address.
+    if entry_id && !entry_id.empty?
+      lookup.selected = entry_id
+      suggestions = client.send(lookup)
+
+      puts
+      puts '*** Secondaries ***'
+      puts
+
+      suggestions.each do |suggestion|
+        puts "#{suggestion.street_line} #{suggestion.city}, #{suggestion.state}"
+      end
+    end
+  end
+end
+
+USAutocompleteExample.new.run

data/lib/smartystreets_ruby_sdk/client_builder.rb

@@ -17,6 +17,7 @@ require_relative 'international_street/client'
 require_relative 'international_autocomplete/client'
 require_relative 'us_reverse_geo/client'
 require_relative 'us_autocomplete_pro/client'
+require_relative 'us_autocomplete/client'
 require_relative 'us_enrichment/client'
 require_relative 'international_postal_code/client'
 
@@ -28,6 +29,7 @@ module SmartyStreets
     INTERNATIONAL_STREET_API_URL = 'https://international-street.api.smarty.com/verify'.freeze
     INTERNATIONAL_AUTOCOMPLETE_API_URL = "https://international-autocomplete.api.smarty.com/v2/lookup".freeze
     US_AUTOCOMPLETE_PRO_API_URL = 'https://us-autocomplete-pro.api.smarty.com/lookup'.freeze
+    US_AUTOCOMPLETE_API_URL = 'https://us-autocomplete.api.smarty.com/v2/lookup'.freeze
     US_EXTRACT_API_URL = 'https://us-extract.api.smarty.com/'.freeze
     US_STREET_API_URL = 'https://us-street.api.smarty.com/street-address'.freeze
     US_ZIP_CODE_API_URL = 'https://us-zipcode.api.smarty.com/lookup'.freeze
@@ -185,6 +187,11 @@ module SmartyStreets
       USAutocompletePro::Client.new(build_sender, @serializer)
     end
 
+    def build_us_autocomplete_api_client
+      ensure_url_prefix_not_null(US_AUTOCOMPLETE_API_URL)
+      USAutocomplete::Client.new(build_sender, @serializer)
+    end
+
     def build_us_extract_api_client
       ensure_url_prefix_not_null(US_EXTRACT_API_URL)
       USExtract::Client.new(build_sender, @serializer)

data/lib/smartystreets_ruby_sdk/us_autocomplete/client.rb

@@ -0,0 +1,82 @@
+require_relative '../request'
+require_relative '../exceptions'
+require_relative 'geolocation_type'
+require_relative 'suggestion'
+
+module SmartyStreets
+  module USAutocomplete
+    # It is recommended to instantiate this class using ClientBuilder.build_us_autocomplete_api_client
+    class Client
+      def initialize(sender, serializer)
+        @sender = sender
+        @serializer = serializer
+      end
+
+      # Sends a Lookup object to the US Autocomplete API and stores the result in the Lookup's result field.
+      def send(lookup)
+        if not lookup or not lookup.search
+          raise SmartyStreets::SmartyError, 'Send() must be passed a Lookup with the search field set.'
+        end
+
+        request = build_request(lookup)
+
+        response = @sender.send(request)
+
+        raise response.error if response.error
+
+        result = @serializer.deserialize(response.payload)
+        suggestions = convert_suggestions(result.fetch('suggestions', []))
+        lookup.result = suggestions
+      end
+
+
+      def build_request(lookup)
+        request = Request.new
+
+        add_parameter(request, 'search', lookup.search)
+        add_parameter(request, 'max_results', lookup.max_results.to_s)
+        add_parameter(request, 'include_only_cities', build_filter_string(lookup.city_filter))
+        add_parameter(request, 'include_only_states', build_filter_string(lookup.state_filter))
+        add_parameter(request, 'include_only_zip_codes', build_filter_string(lookup.zip_filter))
+        add_parameter(request, 'exclude_states', build_filter_string(lookup.exclude_states))
+        add_parameter(request, 'prefer_cities', build_filter_string(lookup.prefer_cities))
+        add_parameter(request, 'prefer_states', build_filter_string(lookup.prefer_states))
+        add_parameter(request, 'prefer_zip_codes', build_filter_string(lookup.prefer_zip_codes))
+        add_parameter(request, 'prefer_ratio', lookup.prefer_ratio.to_s)
+        add_parameter(request, 'source', lookup.source)
+        if lookup.prefer_zip_codes.any? || lookup.zip_filter.any?
+          request.parameters['prefer_geolocation'] = GeolocationType::NONE
+        else
+          add_parameter(request, 'prefer_geolocation', lookup.prefer_geolocation)
+        end
+        add_parameter(request, 'selected', lookup.selected)
+        add_parameter(request, 'exclude', build_filter_string(lookup.exclude, ','))
+
+        for key in lookup.custom_param_hash.keys do
+          add_parameter(request, key, lookup.custom_param_hash[key])
+        end
+
+        request
+      end
+
+      def build_filter_string(filter_list, separator=';')
+        filter_list ? filter_list.join(separator) : nil
+      end
+
+      def convert_suggestions(suggestion_hashes)
+        converted_suggestions = []
+        return converted_suggestions if suggestion_hashes.nil?
+
+        suggestion_hashes.each do |suggestion|
+          converted_suggestions.push(USAutocomplete::Suggestion.new(suggestion))
+        end
+
+        converted_suggestions
+      end
+
+      def add_parameter(request, key, value)
+        request.parameters[key] = value unless value.nil? or value.empty?
+      end
+    end
+  end
+end

data/lib/smartystreets_ruby_sdk/us_autocomplete/geolocation_type.rb

@@ -0,0 +1,8 @@
+module SmartyStreets
+  module USAutocomplete
+    module GeolocationType
+      CITY = 'city'
+      NONE = 'none'
+    end
+  end
+end

data/lib/smartystreets_ruby_sdk/us_autocomplete/lookup.rb

@@ -0,0 +1,73 @@
+require_relative '../json_able'
+
+module SmartyStreets
+  module USAutocomplete
+    # In addition to holding all of the input data for this lookup, this class also will contain the result
+    # of the lookup after it comes back from the API.
+    #
+    # See "https://www.smarty.com/docs/apis/us-autocomplete-v2/reference#http-request-input-fields"
+    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, :exclude, :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, exclude=nil, source=nil, custom_param_hash=nil)
+        @result = []
+        @search = search
+        @max_results = max_results
+        @city_filter = city_filter ? city_filter : []
+        @state_filter = state_filter ? state_filter : []
+        @zip_filter = zip_filter ? zip_filter : []
+        @exclude_states = exclude_states ? exclude_states : []
+        @prefer_cities = prefer_cities ? prefer_cities : []
+        @prefer_states = prefer_states ? prefer_states : []
+        @prefer_zip_codes = prefer_zips ? prefer_zips : []
+        @prefer_ratio = prefer_ratio
+        @prefer_geolocation = prefer_geolocation
+        @selected = selected
+        @exclude = exclude ? exclude : []
+        @source = source
+        @custom_param_hash = {}
+      end
+
+      def add_custom_parameter(parameter, value)
+        @custom_param_hash[parameter] = value
+      end
+
+      def add_city_filter(city)
+        @city_filter.push(city)
+      end
+
+      def add_state_filter(state)
+        @state_filter.push(state)
+      end
+
+      def add_zip_filter(zip)
+        @zip_filter.push(zip)
+      end
+
+      def add_state_exclusion(state)
+        @exclude_states.push(state)
+      end
+
+      def add_preferred_city(city)
+        @prefer_cities.push(city)
+      end
+
+      def add_preferred_state(state)
+        @prefer_states.push(state)
+      end
+
+      def add_preferred_zip(zip)
+        @prefer_zip_codes.push(zip)
+      end
+
+      def add_exclude(exclude_type)
+        @exclude.push(exclude_type)
+      end
+    end
+  end
+end

data/lib/smartystreets_ruby_sdk/us_autocomplete/source_type.rb

@@ -0,0 +1,8 @@
+module SmartyStreets
+  module USAutocomplete
+    module SourceType
+      ALL = 'all'.freeze
+      POSTAL = 'postal'.freeze
+    end
+  end
+end

data/lib/smartystreets_ruby_sdk/us_autocomplete/suggestion.rb

@@ -0,0 +1,21 @@
+module SmartyStreets
+  module USAutocomplete
+    # See "https://www.smarty.com/docs/apis/us-autocomplete-v2/reference#http-response-status"
+    class Suggestion
+
+      attr_reader :smarty_key, :entry_id, :street_line, :secondary, :city, :state, :zipcode, :entries, :source
+
+      def initialize(obj)
+        @smarty_key = obj.fetch('smarty_key', nil)
+        @entry_id = obj.fetch('entry_id', nil)
+        @street_line = obj.fetch('street_line', nil)
+        @secondary = obj.fetch('secondary', nil)
+        @city = obj.fetch('city', nil)
+        @state = obj.fetch('state', nil)
+        @zipcode = obj.fetch('zipcode', nil)
+        @entries = obj.fetch('entries', 0)
+        @source = obj.fetch('source', nil)
+      end
+    end
+  end
+end

data/lib/smartystreets_ruby_sdk/us_autocomplete.rb

@@ -0,0 +1,10 @@
+require_relative './us_autocomplete/lookup'
+require_relative './us_autocomplete/geolocation_type'
+require_relative './us_autocomplete/source_type'
+require_relative './us_autocomplete/suggestion'
+require_relative './us_autocomplete/client'
+
+module SmartyStreets
+  module USAutocomplete
+  end
+end

data/lib/smartystreets_ruby_sdk/version.rb

@@ -1,3 +1,3 @@
 module SmartyStreets
-  VERSION = '9.0.0' # DO NOT EDIT (this is updated by a build job when a new release is published)
+  VERSION = '9.1.0' # DO NOT EDIT (this is updated by a build job when a new release is published)
 end

data/lib/smartystreets_ruby_sdk.rb

@@ -24,6 +24,7 @@ require 'smartystreets_ruby_sdk/us_extract'
 require 'smartystreets_ruby_sdk/us_street'
 require 'smartystreets_ruby_sdk/us_zipcode'
 require 'smartystreets_ruby_sdk/us_autocomplete_pro'
+require 'smartystreets_ruby_sdk/us_autocomplete'
 require 'smartystreets_ruby_sdk/international_street'
 require 'smartystreets_ruby_sdk/international_autocomplete'
 require 'smartystreets_ruby_sdk/international_postal_code'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: smartystreets_ruby_sdk
 version: !ruby/object:Gem::Version
-  version: 9.0.0
+  version: 9.1.0
 platform: ruby
 authors:
 - SmartyStreets SDK Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-23 00:00:00.000000000 Z
+date: 2026-06-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -98,6 +98,7 @@ files:
 - examples/international_autocomplete_example.rb
 - examples/international_example.rb
 - examples/international_postal_code_example.rb
+- examples/us_autocomplete_example.rb
 - examples/us_autocomplete_pro_example.rb
 - examples/us_enrichment_business_example.rb
 - examples/us_enrichment_business_name_search_example.rb
@@ -153,6 +154,12 @@ files:
 - lib/smartystreets_ruby_sdk/static_credentials.rb
 - lib/smartystreets_ruby_sdk/status_code_sender.rb
 - lib/smartystreets_ruby_sdk/url_prefix_sender.rb
+- lib/smartystreets_ruby_sdk/us_autocomplete.rb
+- lib/smartystreets_ruby_sdk/us_autocomplete/client.rb
+- lib/smartystreets_ruby_sdk/us_autocomplete/geolocation_type.rb
+- lib/smartystreets_ruby_sdk/us_autocomplete/lookup.rb
+- lib/smartystreets_ruby_sdk/us_autocomplete/source_type.rb
+- lib/smartystreets_ruby_sdk/us_autocomplete/suggestion.rb
 - lib/smartystreets_ruby_sdk/us_autocomplete_pro.rb
 - lib/smartystreets_ruby_sdk/us_autocomplete_pro/client.rb
 - lib/smartystreets_ruby_sdk/us_autocomplete_pro/geolocation_type.rb