SmartyStreets Ruby SDK

If you want to access our APIs (other than the Download API) from a Ruby application, the SmartyStreets Ruby SDK can make it a lot easier. Our Ruby SDK includes ready-made data structures and takes care of all the gritty, low-level HTTP intricacies for you.

Contents

  1. Requirements
  2. How to Get It
    1. RubyGems
    2. Downloading the files directly
  3. How to Use It
    1. Verifying a Single US Street Address
    2. Verifying Multiple US Street Addresses
    3. Sending a Single Lookup to the US ZIP Code API
    4. Sending Multiple Lookups to the US ZIP Code API
    5. Sending the Beginning of an Address to the US Autocomplete API
    6. Sending Text to the US Extract API
    7. Verifying an International Street Address
  4. API Reference Material

Requirements

  1. Have a Ruby project that is written for Ruby 2.0 or higher.
  2. Realize that you need an address verification component.
  3. Wisely conclude that you don't want to build your own address verification component.
  4. Realize that SmartyStreets has already created an address verification component.
  5. Congratulations! You are now ready to use the SmartyStreets Ruby SDK.

How to Get It

RubyGems

The easiest way to get your giddy hands on this goodness is by using RubyGems.
Be sure RubyGems is installed, then just pop open your terminal and run

$ gem install smartystreets_ruby_sdk


Alternately, you can add this line to your application's Gemfile:

gem 'smartystreets_ruby_sdk'


Then execute:

$ bundle

Downloading the files directly

You can download the source code or the .gem file from Github here.

How to Use It

Here are a few pieces of example code to show how to use our Ruby library/SDK.

Verifying a Single US Street Address

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 = ENV['SMARTY_AUTH_ID'] # We recommend storing your keys in environment variables
    auth_token = ENV['SMARTY_AUTH_TOKEN']
    credentials = StaticCredentials.new(auth_id, auth_token)

    client = ClientBuilder.new(credentials).build_us_street_api_client

    lookup = USStreet::Lookup.new
    lookup.street = '1600 Amphitheatre Pkwy'
    lookup.city = 'Mountain View'
    lookup.state = 'CA'

    begin
      client.send_lookup(lookup)
    rescue SmartyException => err
      puts err
      return
    end

    result = lookup.result

    if result nil?
      puts 'No candidates. This means the address is not valid.'
      return
    end

    first_candidate = result[0]

    puts "Address is valid. (There is at least one candidate)\n"
    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

Verifying Multiple US Street Addresses

require 'smartystreets_ruby_sdk/static_credentials'
require 'smartystreets_ruby_sdk/client_builder'
require 'smartystreets_ruby_sdk/us_street/lookup'

class USStreetMultipleAddressExample
  Lookup = USStreet::Lookup

  def run
    auth_id = ENV['SMARTY_AUTH_ID'] # We recommend storing your keys in environment variables.
    auth_token = ENV['SMARTY_AUTH_TOKEN']
    credentials = StaticCredentials.new(auth_id, auth_token)

    client = ClientBuilder.new(credentials).build_us_street_api_client
    batch = Batch.new

    batch.add(Lookup.new)
    batch[0].street = '1600 amphitheatre parkway'
    batch[0].city = 'Mountain view'
    batch[0].state = 'california'

    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 SmartyException => 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} is valid. (There is at least one candidate)"

      candidates.each do |candidate|
        components = candidate.components
        metadata = candidate.metadata

        puts "\nCandidate #{candidate.candidate_index} : "
        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

Sending a Single Lookup to the US ZIP Code API

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 = ENV['SMARTY_AUTH_ID'] # We recommend storing your keys in environment variables.
    auth_token = ENV['SMARTY_AUTH_TOKEN']
    credentials = StaticCredentials.new(auth_id, auth_token)

    client = ClientBuilder.new(credentials).build_us_zipcode_api_client

    lookup = USZipcode::Lookup.new
    lookup.city = 'Mountain View'
    lookup.state = 'California'

    begin
      client.send_lookup(lookup)
    rescue SmartyException => err
      puts err
      return
    end

    result = lookup.result
    zipcodes = result.zipcodes
    cities = result.cities

    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

Sending Multiple Lookups to the US ZIP Code API

require 'smartystreets_ruby_sdk/static_credentials'
require 'smartystreets_ruby_sdk/client_builder'
require 'smartystreets_ruby_sdk/us_zipcode/lookup'

class USZipcodeMultipleLookupExample
  Lookup = USZipcode::Lookup

  def run
    auth_id = ENV['SMARTY_AUTH_ID'] # We recommend storing your keys in environment variables
    auth_token = ENV['SMARTY_AUTH_TOKEN']
    credentials = StaticCredentials.new(auth_id, auth_token)

    client = ClientBuilder.new(credentials).build_us_zipcode_api_client
    batch = Batch.new

    batch.add(Lookup.new)
    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 SmartyException => 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

Sending the Beginning of an Address to the US Autocomplete API

require 'smartystreets_ruby_sdk/static_credentials'
require 'smartystreets_ruby_sdk/client_builder'
require 'smartystreets_ruby_sdk/us_autocomplete/lookup'

class USAutocompleteExample
  Lookup = USAutocomplete::Lookup

  def run
    auth_id = ENV['SMARTY_AUTH_ID'] # We recommend storing your keys in environment variables
    auth_token = ENV['SMARTY_AUTH_TOKEN']
    credentials = StaticCredentials.new(auth_id, auth_token)
    client = ClientBuilder.new(credentials).build_us_autocomplete_api_client
    lookup = Lookup.new('4770 Lincoln Ave O')

    client.send(lookup)

    puts '*** Result with no filter ***'
    puts
    lookup.result.each do |suggestion|
      puts suggestion.text
    end

    lookup.add_state_filter('IL')
    lookup.max_suggestions = 5

    suggestions = client.send(lookup) # The client will also return the suggestions directly

    puts
    puts '*** Result with some filters ***'

    suggestions.each do |suggestion|
      puts suggestion.text
    end

  end
end

USAutocompleteExample.new.run

Sending Text to the US Extract API

require 'smartystreets_ruby_sdk/static_credentials'
require 'smartystreets_ruby_sdk/client_builder'
require 'smartystreets_ruby_sdk/us_extract/lookup'

class USExtractExample
  Lookup = USExtract::Lookup

  def run
    auth_id = ENV['SMARTY_AUTH_ID'] # We recommend storing your keys in environment variables
    auth_token = ENV['SMARTY_AUTH_TOKEN']
    credentials = StaticCredentials.new(auth_id, auth_token)

    client = ClientBuilder.new(credentials).build_us_extract_api_client

    text = "Here is some text.\r\nMy address is 3785 Las Vegs Av." \
           "\r\nLos Vegas, Nevada." \
           "\r\nMeet me at 1 Rosedale Baltimore Maryland, not at 123 Phony Street, Boise Idaho."

    lookup = Lookup.new(text)

    result = client.send(lookup)

    metadata = result.metadata
    puts "Found #{metadata.address_count} addresses."
    puts "#{metadata.verified_count} of them were valid."
    puts

    addresses = result.addresses

    puts "Addresses: \r\n**********************\r\n"
    addresses.each do |address|
      puts "\"#{address.text}\"\n\n"
      puts "Verified? #{address.verified}"
      if address.candidates.any?
        puts("\nMatches:")

        address.candidates.each do |candidate|
          puts candidate.delivery_line_1
          puts candidate.last_line
          puts
        end

      else
        puts
      end

      puts "**********************\n"
    end
  end
end

USExtractExample.new.run

Verifying an International Street Address

require 'smartystreets_ruby_sdk/static_credentials'
require 'smartystreets_ruby_sdk/client_builder'
require 'smartystreets_ruby_sdk/international_street/lookup'

class InternationalExample
  Lookup = InternationalStreet::Lookup

  def run
    auth_id = ENV['SMARTY_AUTH_ID'] # We recommend storing your keys in environment variables
    auth_token = ENV['SMARTY_AUTH_TOKEN']
    credentials = StaticCredentials.new(auth_id, auth_token)
    client = ClientBuilder.new(credentials).build_international_street_api_client

    lookup = Lookup.new("Rua Padre Antonio D'Angelo 121 Casa Verde, Sao Paulo", 'Brazil')
    lookup.geocode = true # Must be expressly set to get latitude and longitude.

    candidates = client.send(lookup) # The candidates are also stored in the lookup's 'result' field.

    first_candidate = candidates[0]
    puts "Address is #{first_candidate.analysis.verification_status}"
    puts "Address precision: #{first_candidate.analysis.address_precision}\n\n"
    puts "First Line: #{first_candidate.address1}"
    puts "Second Line: #{first_candidate.address2}"
    puts "Third Line: #{first_candidate.address3}"
    puts "Fourth Line: #{first_candidate.address4}"
    puts "Latitude: #{first_candidate.metadata.latitude}"
    puts "Longitude: #{first_candidate.metadata.longitude}"
  end
end

InternationalExample.new.run

Product Features Demo Pricing Help Company Documentation Articles Contact Customers Legal Stuff