Ruby SDK

A Ruby client for Smarty's address verification, geocoding, autocomplete, and data enrichment APIs.

The Smarty Ruby SDK enables you to integrate address intelligence into your Ruby applications with minimal boilerplate. Whether you're validating millions of addresses, enriching them with precise geocodes, or powering an autocomplete form, the Ruby SDK gives you a clear way to call every Smarty API.

Contents

1. Installation
2. Authentication
3. Create an API client
4. Create and send lookups
5. Examine results
6. More examples

Installation

The Ruby SDK is available via RubyGems. You can use the command below to install it:

gem install smartystreets_ruby_sdk

Or you can put the below line in your Gemfile:

gem 'smartystreets_ruby_sdk'

Then run the bundler:

bundle

Authentication

Smarty offers two kinds of credentials depending on where your code runs:

• Server-side (backend, CLI, batch jobs)
  Use Auth ID + Auth Token (a Secret Key pair).
• Client-side (browser, front-end, public UI)
  Use Auth Web + Auth Referer (a Website Key pair restricted by domain).

You can find all keys in your Smarty account under:
Account → API Keys

We recommend storing your credentials in environment variables for security:

export SMARTY_AUTH_ID="your-auth-id"
export SMARTY_AUTH_TOKEN="your-auth-token"
export SMARTY_AUTH_WEB="your-auth-web"
export SMARTY_AUTH_REFERER="your-auth-referer"
	

For details on authentication and embedded vs. secret keys, see our authentication documentation.

Create an API client

The SDK offers different client builders for each API. You can create one by invoking the ClientBuilder class.

Server-side client

Here's an example for us_street:

id = ENV['SMARTY_AUTH_ID']
token = ENV['SMARTY_AUTH_TOKEN']
credentials = SmartyStreets::BasicAuthCredentials.new(id, token)

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

Browser/Frontend client

Here's an example for international_autocomplete:

key = ENV['SMARTY_AUTH_WEB']
referer = ENV['SMARTY_AUTH_REFERER']
credentials = SmartyStreets::SharedCredentials.new(key, referer)

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

You can find a full list of API clients and options here.

Create and send lookups

Create lookups based on the addresses you want to validate. Here's an example for us_street:

batch = SmartyStreets::Batch.new
lookup = SmartyStreets::USStreet::Lookup.new

lookup.street = '1600 amphitheatre parkway'
lookup.lastline = 'Mountain view, California'
lookup.zipcode = '21229'

batch.add(lookup)

# You can also create a lookup freeform with the constructor

batch.add(SmartyStreets::USStreet::Lookup.new('1 Rosedale, Baltimore, Maryland'))
	

Then, send the batch using the client you created earlier:

begin
	client.send_batch(batch)
rescue SmartyStreets::SmartyError => err
	puts err
	return
end
	

Examine results

Review the results returned by the API:

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}"
end
	

More examples

• US Street API
• US Autocomplete Pro API
• US Enrichment API
• US Extract API
• US Reverse Geocoding API
• US ZIP Code API
• International Autocomplete API
• International Street API

More examples can be found on the Ruby SDK GitHub here.