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 = '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).
								# Uncomment the line below to try it with a proxy
								# with_proxy('localhost', 8080, 'proxyUser', 'proxyPassword').
								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 = '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_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 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 = '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

		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 = '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

		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'

		# You can also set these fields with arguments
		batch.add(Lookup.new('cupertino', 'CA', '95014'))


		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 = '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_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 ***'
		puts

		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 = '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_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 = '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_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
This site uses cookies for analytics, personalized content, and ads. By continuing to browse this site, you agree to this use.