smartystreets_ruby_sdk 0.0.0

data/examples/us_reverse_geo_example.rb

@@ -0,0 +1,47 @@
+require 'smartystreets_ruby_sdk/static_credentials'
+require '../lib/smartystreets_ruby_sdk/client_builder'
+require '../lib/smartystreets_ruby_sdk/us_reverse_geo/lookup'
+
+class USReverseGeoExample
+  Lookup = SmartyStreets::USReverseGeo::Lookup
+
+  def run
+    # auth_id = 'Your SmartyStreets Auth ID here'
+    # auth_token = 'Your SmartyStreets Auth Token here'
+
+    # We recommend storing your secret keys in environment variables instead---it's safer!
+    auth_id = ENV['SMARTY_AUTH_ID']
+    auth_token = ENV['SMARTY_AUTH_TOKEN']
+
+    credentials = SmartyStreets::StaticCredentials.new(auth_id, auth_token)
+
+    # The appropriate license values to be used for your subscriptions
+    # can be found on the Subscriptions page of the account dashboard.
+    # https://www.smartystreets.com/docs/cloud/licensing
+    client = SmartyStreets::ClientBuilder.new(credentials).with_licenses(['us-reverse-geocoding-cloud'])
+                 .build_us_reverse_geo_api_client
+
+    # Documentation for input fields can be found at:
+    # https://smartystreets.com/docs/cloud/us-reverse-geo-api#http-request-input-fields
+
+    lookup = Lookup.new(40.111111, -111.111111)
+
+    response = client.send(lookup)
+    result = response.results[0]
+
+    coordinate = result.coordinate
+    puts "Latitude: #{coordinate.latitude}"
+    puts "Longitude: #{coordinate.longitude}\n"
+
+    puts "Distance: #{result.distance}\n"
+
+    address = result.address
+    puts "Street: #{address.street}"
+    puts "City: #{address.city}"
+    puts "State Abbreviation: #{address.state_abbreviation}"
+    puts "ZIP Code: #{address.zipcode}"
+    puts "License: #{coordinate.get_license}"
+  end
+end
+
+USReverseGeoExample.new.run

data/examples/us_street_multiple_address_example.rb

@@ -0,0 +1,87 @@
+require 'smartystreets_ruby_sdk/static_credentials'
+require 'smartystreets_ruby_sdk/client_builder'
+require 'smartystreets_ruby_sdk/batch'
+require 'smartystreets_ruby_sdk/us_street/lookup'
+
+class USStreetMultipleAddressExample
+  Lookup = SmartyStreets::USStreet::Lookup
+
+  def run
+    # auth_id = 'Your SmartyStreets Auth ID here'
+    # auth_token = 'Your SmartyStreets Auth Token here'
+
+    # We recommend storing your secret keys in environment variables instead---it's safer!
+    auth_id = ENV['SMARTY_AUTH_ID']
+    auth_token = ENV['SMARTY_AUTH_TOKEN']
+
+    credentials = SmartyStreets::StaticCredentials.new(auth_id, auth_token)
+
+    # The appropriate license values to be used for your subscriptions
+    # can be found on the Subscriptions page of the account dashboard.
+    # https://www.smartystreets.com/docs/cloud/licensing
+    client = SmartyStreets::ClientBuilder.new(credentials).with_licenses(['us-core-cloud'])
+                 .build_us_street_api_client
+    batch = SmartyStreets::Batch.new
+
+    # Documentation for input fields can be found at:
+    # https://smartystreets.com/docs/cloud/us-street-api
+
+    batch.add(Lookup.new)
+    batch[0].input_id = '8675309'  # Optional ID from your system
+    batch[0].addressee = 'John Doe'
+    batch[0].street = '1600 amphitheatre parkway'
+    batch[0].street2 = 'second star to the right'
+    batch[0].secondary = 'APT 2'
+    batch[0].urbanization = ''  # Only applies to Puerto Rico addresses
+    batch[0].lastline = 'Mountain view, California'
+    batch[0].zipcode = '21229'
+    batch[0].candidates = 3
+    batch[0].match = Lookup.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.
+
+    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).
+
+    batch.add(Lookup.new('123 Bogus Street, Pretend Lake, Oklahoma'))
+
+    batch.add(Lookup.new)
+    batch[3].street = '1 Infinite Loop'
+    batch[3].zipcode = '95014' # You can just input the street and ZIP if you want.
+
+    begin
+      client.send_batch(batch)
+    rescue SmartyStreets::SmartyError => err
+      puts err
+      return
+    end
+
+    batch.each_with_index do |lookup, i|
+      candidates = lookup.result
+
+      if candidates.empty?
+        puts "Address #{i} is invalid.\n\n"
+        next
+      end
+
+      puts "Address #{i} has at least one candidate.\n If the match parameter is set to STRICT, the address is valid.\n Otherwise, check the Analysis output fields to see if the address is valid."
+
+      candidates.each do |candidate|
+        components = candidate.components
+        metadata = candidate.metadata
+
+        puts "\nCandidate #{candidate.candidate_index} : "
+        puts "Input ID: #{candidate.input_id}"
+        puts "Delivery line 1: #{candidate.delivery_line_1}"
+        puts "Last line:       #{candidate.last_line}"
+        puts "ZIP Code:        #{components.zipcode}-#{components.plus4_code}"
+        puts "County:          #{metadata.county_name}"
+        puts "Latitude:        #{metadata.latitude}"
+        puts "Longitude:       #{metadata.longitude}"
+        puts
+      end
+    end
+  end
+end
+
+USStreetMultipleAddressExample.new.run

data/examples/us_street_single_address_example.rb

@@ -0,0 +1,67 @@
+require 'smartystreets_ruby_sdk/static_credentials'
+require 'smartystreets_ruby_sdk/client_builder'
+require 'smartystreets_ruby_sdk/us_street/lookup'
+
+class USStreetSingleAddressExample
+  def run
+    # auth_id = 'Your SmartyStreets Auth ID here'
+    # auth_token = 'Your SmartyStreets Auth Token here'
+
+    # We recommend storing your secret keys in environment variables instead---it's safer!
+    auth_id = ENV['SMARTY_AUTH_ID']
+    auth_token = ENV['SMARTY_AUTH_TOKEN']
+
+    credentials = SmartyStreets::StaticCredentials.new(auth_id, auth_token)
+
+    # The appropriate license values to be used for your subscriptions
+    # can be found on the Subscriptions page of the account dashboard.
+    # https://www.smartystreets.com/docs/cloud/licensing
+    client = SmartyStreets::ClientBuilder.new(credentials).with_licenses(['us-core-cloud'])
+        # with_proxy('localhost', 8080, 'proxyUser', 'proxyPassword'). # Uncomment this line to try it with a proxy
+        build_us_street_api_client
+
+    # Documentation for input fields can be found at:
+    # https://smartystreets.com/docs/cloud/us-street-api
+
+    lookup = SmartyStreets::USStreet::Lookup.new
+    lookup.input_id = '24601'  # Optional ID from your system
+    lookup.addressee = 'John Doe'
+    lookup.street = '1600 Amphitheatre Pkwy'
+    lookup.street2 = 'closet under the stairs'
+    lookup.secondary = 'APT 2'
+    lookup.urbanization = ''  # Only applies to Puerto Rico addresses
+    lookup.city = 'Mountain View'
+    lookup.state = 'CA'
+    lookup.zipcode = '21229'
+    lookup.candidates = 3
+    lookup.match = Lookup.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.
+
+    begin
+      client.send_lookup(lookup)
+    rescue SmartyStreets::SmartyError => err
+      puts err
+      return
+    end
+
+    result = lookup.result
+
+    if result.empty?
+      puts 'No candidates. This means the address is not valid.'
+      return
+    end
+
+    first_candidate = result[0]
+
+    puts "There is at least one candidate.\n If the match parameter is set to STRICT, the address is valid.\n Otherwise, check the Analysis output fields to see if the address is valid.\n"
+    puts "Input ID: #{first_candidate.input_id}"
+    puts "ZIP Code: #{first_candidate.components.zipcode}"
+    puts "County: #{first_candidate.metadata.county_name}"
+    puts "Latitude: #{first_candidate.metadata.latitude}"
+    puts "Longitude: #{first_candidate.metadata.longitude}"
+  end
+end
+
+example = USStreetSingleAddressExample.new
+example.run

data/examples/us_zipcode_multiple_lookup_example.rb

@@ -0,0 +1,80 @@
+require 'smartystreets_ruby_sdk/static_credentials'
+require 'smartystreets_ruby_sdk/client_builder'
+require 'smartystreets_ruby_sdk/batch'
+require 'smartystreets_ruby_sdk/us_zipcode/lookup'
+
+class USZipcodeMultipleLookupExample
+  Lookup = SmartyStreets::USZipcode::Lookup
+
+  def run
+    # auth_id = 'Your SmartyStreets Auth ID here'
+    # auth_token = 'Your SmartyStreets Auth Token here'
+
+    # We recommend storing your secret keys in environment variables instead---it's safer!
+    auth_id = ENV['SMARTY_AUTH_ID']
+    auth_token = ENV['SMARTY_AUTH_TOKEN']
+
+    credentials = SmartyStreets::StaticCredentials.new(auth_id, auth_token)
+
+    client = SmartyStreets::ClientBuilder.new(credentials).build_us_zipcode_api_client
+    batch = SmartyStreets::Batch.new
+
+    # Documentation for input fields can be found at:
+    # https://smartystreets.com/docs/cloud/us-zipcode-api
+
+    batch.add(Lookup.new)
+    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.add(Lookup.new)
+    batch[1].city = 'Phoenix'
+    batch[1].state = 'Arizona'
+
+    batch.add(Lookup.new('cupertino', 'CA', '95014')) # You can also set these with arguments
+
+
+    begin
+      client.send_batch(batch)
+    rescue SmartyError => err
+      puts err
+      return
+    end
+
+    batch.each_with_index { |lookup, i|
+      result = lookup.result
+      puts "Lookup #{i}:\n"
+
+      if result.status
+        puts "Status: #{result.status}"
+        puts "Reason: #{result.reason}"
+        next
+      end
+
+      cities = result.cities
+      puts "#{cities.length} City and State match(es):"
+
+      cities.each { |city|
+        puts "City: #{city.city}"
+        puts "State: #{city.state}"
+        puts "Mailable City: #{city.mailable_city}"
+        puts
+      }
+
+      zipcodes = result.zipcodes
+      puts "#{zipcodes.length} ZIP Code match(es):"
+
+      zipcodes.each { |zipcode|
+        puts "ZIP Code: #{zipcode.zipcode}"
+        puts "County: #{zipcode.county_name}"
+        puts "Latitude: #{zipcode.latitude}"
+        puts "Longitude: #{zipcode.longitude}"
+        puts
+      }
+
+      puts '***********************************'
+    }
+  end
+end
+
+example = USZipcodeMultipleLookupExample.new
+example.run

data/examples/us_zipcode_single_lookup_example.rb

@@ -0,0 +1,55 @@
+require 'smartystreets_ruby_sdk/static_credentials'
+require 'smartystreets_ruby_sdk/client_builder'
+require 'smartystreets_ruby_sdk/us_zipcode/lookup'
+
+class UsZipcodeSingleLookupExample
+  def run
+    # auth_id = 'Your SmartyStreets Auth ID here'
+    # auth_token = 'Your SmartyStreets Auth Token here'
+
+    # We recommend storing your secret keys in environment variables instead---it's safer!
+    auth_id = ENV['SMARTY_AUTH_ID']
+    auth_token = ENV['SMARTY_AUTH_TOKEN']
+
+    credentials = SmartyStreets::StaticCredentials.new(auth_id, auth_token)
+
+    client = SmartyStreets::ClientBuilder.new(credentials).build_us_zipcode_api_client
+
+    # Documentation for input fields can be found at:
+    # https://smartystreets.com/docs/cloud/us-zipcode-api
+
+    lookup = SmartyStreets::USZipcode::Lookup.new
+    lookup.input_id = 'dfc33cb6-829e-4fea-aa1b-b6d6580f0817'  # Optional ID from your system
+    lookup.city = 'Mountain View'
+    lookup.state = 'California'
+    lookup.zipcode = '94043'
+
+    begin
+      client.send_lookup(lookup)
+    rescue SmartyStreets::SmartyError => err
+      puts err
+      return
+    end
+
+    result = lookup.result
+    zipcodes = result.zipcodes
+    cities = result.cities
+
+    puts "Input ID: #{result.input_id}"
+
+    cities.each do |city|
+      puts "\nCity: #{city.city}"
+      puts "State: #{city.state}"
+      puts "Mailable City: #{city.mailable_city}"
+    end
+
+    zipcodes.each do |zipcode|
+      puts "\nZIP Code: #{zipcode.zipcode}"
+      puts "Latitude: #{zipcode.latitude}"
+      puts "Longitude: #{zipcode.longitude}"
+    end
+  end
+end
+
+example = UsZipcodeSingleLookupExample.new
+example.run

data/lib/smartystreets_ruby_sdk/batch.rb

@@ -0,0 +1,59 @@
+module SmartyStreets
+  # The Batch class is used to send up to 100 lookups at once
+  class Batch
+    include Enumerable
+    MAX_BATCH_SIZE = 100
+
+    attr_reader :all_lookups, :named_lookups
+
+    def initialize
+      @named_lookups = {}
+      @all_lookups = []
+    end
+
+    def add(lookup)
+      return false if full?
+
+      @all_lookups.push(lookup)
+
+      return true if lookup.input_id.nil?
+
+      @named_lookups[lookup.input_id] = lookup
+      true
+    end
+
+    def clear
+      @named_lookups.clear
+      @all_lookups.clear
+    end
+
+    def full?
+      size >= MAX_BATCH_SIZE
+    end
+
+    def empty?
+      size.zero?
+    end
+
+    def size
+      @all_lookups.length
+    end
+
+    def get_by_input_id(input_id)
+      @named_lookups[input_id]
+    end
+
+    def get_by_index(index)
+      @all_lookups[index]
+    end
+
+    def each(&block)
+      @all_lookups.each(&block)
+    end
+
+    def [](index)
+      @all_lookups[index]
+    end
+
+  end
+end

data/lib/smartystreets_ruby_sdk/client_builder.rb

@@ -0,0 +1,188 @@
+require_relative 'native_serializer'
+require_relative 'native_sender'
+require_relative 'status_code_sender'
+require_relative 'signing_sender'
+require_relative 'retry_sender'
+require_relative 'url_prefix_sender'
+require_relative 'license_sender'
+require_relative 'sleeper'
+require_relative 'logger'
+require_relative 'proxy'
+require_relative 'custom_header_sender'
+require_relative 'us_street/client'
+require_relative 'us_zipcode/client'
+require_relative 'us_extract/client'
+require_relative 'us_autocomplete/client'
+require_relative 'international_street/client'
+require_relative 'us_reverse_geo/client'
+require_relative 'us_autocomplete_pro/client'
+
+module SmartyStreets
+  # The ClientBuilder class helps you build a client object for one of the supported SmartyStreets APIs.
+  # You can use ClientBuilder's methods to customize settings like maximum retries or timeout duration.
+  # These methods are chainable, so you can usually get set up with one line of code.
+  class ClientBuilder
+    INTERNATIONAL_STREET_API_URL = 'https://international-street.api.smartystreets.com/verify'.freeze
+    INTERNATIONAL_AUTOCOMPLETE_API_URL = "https://international-autocomplete.api.smartystreets.com/lookup".freeze
+    US_AUTOCOMPLETE_API_URL = 'https://us-autocomplete.api.smartystreets.com/suggest'.freeze
+    US_AUTOCOMPLETE_PRO_API_URL = 'https://us-autocomplete-pro.api.smartystreets.com/lookup'.freeze
+    US_EXTRACT_API_URL = 'https://us-extract.api.smartystreets.com/'.freeze
+    US_STREET_API_URL = 'https://us-street.api.smartystreets.com/street-address'.freeze
+    US_ZIP_CODE_API_URL = 'https://us-zipcode.api.smartystreets.com/lookup'.freeze
+    US_REVERSE_GEO_API_URL = 'https://us-reverse-geo.api.smartystreets.com/lookup'.freeze
+
+    def initialize(signer)
+      @signer = signer
+      @serializer = NativeSerializer.new
+      @http_sender = nil
+      @max_retries = 5
+      @max_timeout = 10
+      @url_prefix = nil
+      @proxy = nil
+      @headers = nil
+      @licenses = %w()
+      @debug = nil
+    end
+
+    # Sets the maximum number of times to retry sending the request to the API. (Default is 5)
+    #
+    # Returns self to accommodate method chaining.
+    def retry_at_most(max_retries)
+      @max_retries = max_retries
+      self
+    end
+
+    # The maximum time (in seconds) to wait for the response to be read. (Default is 10)
+    #
+    # Returns self to accommodate method chaining.
+    def with_max_timeout(max_timeout)
+      @max_timeout = max_timeout
+      self
+    end
+
+    # Default is a series of nested senders. (See build_sender()
+    #
+    # Returns self to accommodate method chaining.
+    def with_sender(sender)
+      @http_sender = sender
+      self
+    end
+
+    # Changes the Serializer from the default.
+    #
+    # Returns self to accommodate method chaining.
+    def with_serializer(serializer)
+      @serializer = serializer
+      self
+    end
+
+    # This may be useful when using a local installation of the SmartyStreets APIs.
+    # base_url is a string that defaults to the URL for the API corresponding to the Client object being built.
+    #
+    # Returns self to accommodate method chaining.
+    def with_base_url(base_url)
+      @url_prefix = base_url
+      self
+    end
+
+    # Assigns a proxy through which all requests will be sent.
+    # proxy is a Proxy object from this module.
+    #
+    # Returns self to accommodate method chaining.
+    def with_proxy(host, port, username, password)
+      @proxy = SmartyStreets::Proxy.new(host, port, username, password)
+      self
+    end
+
+    # Allows you to submit custom headers using a Hash.
+    # headers is a Hash object.
+    #
+    # Returns self to accommodate method chaining.
+    def with_custom_headers(headers)
+      @headers = headers
+      self
+    end
+
+    # Allows the caller to specify the subscription license (aka "track") they wish to use.
+    #
+    # Returns self to accommodate method chaining.
+    def with_licenses(licenses)
+      @licenses.concat licenses
+      self
+    end
+
+    # Enables debug mode, which will print information about the HTTP request and response to $stdout.
+    #
+    # Returns self to accommodate method chaining.
+    def with_debug
+      @debug = true
+      self
+    end
+
+    # <editor-fold desc="Build methods">
+
+    def build_international_street_api_client
+      ensure_url_prefix_not_null(INTERNATIONAL_STREET_API_URL)
+      InternationalStreet::Client.new(build_sender, @serializer)
+    end
+
+    def build_international_autocomplete_api_client
+      ensure_url_prefix_not_null(INTERNATIONAL_AUTOCOMPLETE_API_URL)
+      InternationalAutocomplete::Client.new(build_sender, @serializer)
+    end
+
+    def build_us_autocomplete_api_client # Deprecated
+      ensure_url_prefix_not_null(US_AUTOCOMPLETE_API_URL)
+      USAutocomplete::Client.new(build_sender, @serializer)
+    end
+
+    def build_us_autocomplete_pro_api_client
+      ensure_url_prefix_not_null(US_AUTOCOMPLETE_PRO_API_URL)
+      USAutocompletePro::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)
+    end
+
+    def build_us_street_api_client
+      ensure_url_prefix_not_null(US_STREET_API_URL)
+      USStreet::Client.new(build_sender, @serializer)
+    end
+
+    def build_us_zipcode_api_client
+      ensure_url_prefix_not_null(US_ZIP_CODE_API_URL)
+      USZipcode::Client.new(build_sender, @serializer)
+    end
+
+    def build_us_reverse_geo_api_client
+      ensure_url_prefix_not_null(US_REVERSE_GEO_API_URL)
+      USReverseGeo::Client.new(build_sender, @serializer)
+    end
+
+    # </editor-fold>
+
+    def build_sender
+      return @http_sender unless @http_sender.nil?
+
+      sender = NativeSender.new(@max_timeout, @proxy, @debug)
+
+      sender = StatusCodeSender.new(sender)
+
+      sender = CustomHeaderSender.new(sender, @headers) unless @headers.nil?
+
+      sender = SigningSender.new(@signer, sender) unless @signer.nil?
+
+      sender = RetrySender.new(@max_retries, sender, SmartyStreets::Sleeper.new,SmartyStreets::Logger.new) if @max_retries > 0
+
+      sender = LicenseSender.new(sender, @licenses)
+
+      URLPrefixSender.new(@url_prefix, sender)
+    end
+
+    def ensure_url_prefix_not_null(url)
+      @url_prefix = url if @url_prefix.nil?
+    end
+  end
+end

data/lib/smartystreets_ruby_sdk/custom_header_sender.rb

@@ -0,0 +1,13 @@
+module SmartyStreets
+  class CustomHeaderSender
+    def initialize(inner, headers)
+      @inner = inner
+      @headers = headers
+    end
+
+    def send(request)
+      request.headers = @headers
+      @inner.send(request)
+    end
+  end
+end

data/lib/smartystreets_ruby_sdk/errors.rb

@@ -0,0 +1,27 @@
+module SmartyStreets
+  BAD_CREDENTIALS = 'Unauthorized: The credentials were provided incorrectly or did not match any existing,
+ active credentials.'.freeze
+
+  PAYMENT_REQUIRED = 'Payment Required: There is no active subscription
+ for the account associated with the credentials submitted with the request.'.freeze
+
+  FORBIDDEN = 'Because the international service is currently in a limited release phase, only approved accounts' \
+            ' may access the service.'.freeze
+
+  REQUEST_ENTITY_TOO_LARGE = 'Request Entity Too Large: The request body has exceeded the maximum size.'.freeze
+
+  BAD_REQUEST = 'Bad Request (Malformed Payload): A GET request lacked a street field or the request body of a
+ POST request contained malformed JSON, possibly because a value was submitted as a number rather than as a string.'.freeze
+
+  UNPROCESSABLE_ENTITY = 'GET request lacked required fields.'.freeze
+
+  TOO_MANY_REQUESTS = 'When using public "website key" authentication,
+we restrict the number of requests coming from a given source over too short of a time.'.freeze
+
+  INTERNAL_SERVER_ERROR = 'Internal Server Error.'.freeze
+
+  SERVICE_UNAVAILABLE = 'Service Unavailable. Try again later.'.freeze
+
+  GATEWAY_TIMEOUT = 'The upstream data provider did not respond in a timely fashion and the request failed. ' \
+                  'A serious, yet rare occurrence indeed.'.freeze
+end

data/lib/smartystreets_ruby_sdk/exceptions.rb

@@ -0,0 +1,39 @@
+module SmartyStreets
+
+  class SmartyError < StandardError
+  end
+
+  class BadCredentialsError < SmartyError
+  end
+
+  class ForbiddenError < SmartyError
+  end
+
+  class PaymentRequiredError < SmartyError
+  end
+
+  class RequestEntityTooLargeError < SmartyError
+  end
+
+  class BadRequestError < SmartyError
+  end
+
+  class UnprocessableEntityError < SmartyError
+  end
+
+  class TooManyRequestsError < SmartyError
+  end
+
+  class InternalServerError < SmartyError
+  end
+
+  class ServiceUnavailableError < SmartyError
+  end
+
+  class GatewayTimeoutError < SmartyError
+  end
+
+  class BatchFullError < SmartyError
+  end
+
+end