SmartyStreets Ruby SDK

If you want to access our US Street Address API or US ZIP Code 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
  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/us_street/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 = USStreet::ClientBuilder.new(credentials).build

    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/us_street/client_builder'
require 'smartystreets_ruby_sdk/us_street/lookup'

class USStreetMultipleAddressExample
  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 = USStreet::ClientBuilder.new(credentials).build
    batch = Batch.new

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

    batch.add(USStreet::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(USStreet::Lookup.new('123 Bogus Street, Pretend Lake, Oklahoma'))

    batch.add(USStreet::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
      print(err)
      return
    end

    batch.each_with_index do |lookup, i|
      candidates = lookup.result

      if candidates.length == 0
        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/us_zipcode/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 = USZipcode::ClientBuilder.new(credentials).build

    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/us_zipcode/client_builder'
require 'smartystreets_ruby_sdk/us_zipcode/lookup'

class USZipcodeMultipleLookupExample
  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 = USZipcode::ClientBuilder.new(credentials).build
    batch = Batch.new

    batch.add(USZipcode::Lookup.new)
    batch[0].zipcode = '12345' # A Lookup may have a ZIP Code, city and state, or city, state, and ZIP Code.

    batch.add(USZipcode::Lookup.new)
    batch[1].city = 'Phoenix'
    batch[1].state = 'Arizona'

    batch.add(USZipcode::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

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