Documentation

 

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. Download the Source Code
  3. How to Use It
    1. Demo
    2. Verifying a Single US Street Address
    3. Verifying Multiple US Street Addresses
    4. Sending a Single Lookup to the US ZIP Code API
    5. Sending Multiple Lookups to the US ZIP Code API
    6. Sending the Beginning of an Address to the US Autocomplete API
    7. Sending Text to the US Extract API
    8. 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

Download the Source Code

You can download the source code from the SmartyStreets Ruby SDK repository on Github.

Use the source, Luke!

How to Use It

Demo

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 = SmartyStreets::StaticCredentials.new(auth_id, auth_token)

	client = SmartyStreets::ClientBuilder.new(credentials).
				 # with_proxy('localhost', 8080, 'proxyUser', 'proxyPassword'). # Uncomment this line to try it with a proxy
				 build_us_street_api_client

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

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

class USStreetMultipleAddressExample
  Lookup = SmartyStreets::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 = SmartyStreets::StaticCredentials.new(auth_id, auth_token)

	client = SmartyStreets::ClientBuilder.new(credentials).build_us_street_api_client
	batch = SmartyStreets::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 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} 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 = SmartyStreets::StaticCredentials.new(auth_id, auth_token)

	client = SmartyStreets::ClientBuilder.new(credentials).build_us_zipcode_api_client

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

	begin
	  client.send_lookup(lookup)
	rescue SmartyError => 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/batch'
require 'smartystreets_ruby_sdk/us_zipcode/lookup'

class USZipcodeMultipleLookupExample
  Lookup = SmartyStreets::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 = SmartyStreets::StaticCredentials.new(auth_id, auth_token)

	client = SmartyStreets::ClientBuilder.new(credentials).build_us_zipcode_api_client
	batch = SmartyStreets::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 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

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 = SmartyStreets::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 = SmartyStreets::StaticCredentials.new(auth_id, auth_token)
	client = SmartyStreets::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 = SmartyStreets::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 = SmartyStreets::StaticCredentials.new(auth_id, auth_token)

	client = SmartyStreets::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 = SmartyStreets::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 = SmartyStreets::StaticCredentials.new(auth_id, auth_token)
	client = SmartyStreets::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