AddressFinder Ruby Gem
A client library for accessing the AddressFinder APIs.
Installation
Add this line to your application's Gemfile:
gem 'addressfinder'
And then execute:
$ bundle
Or install it yourself as:
$ gem install addressfinder
Configuration
Use the configure block to set your api_key
and api_secret
.
AddressFinder.configure do |af|
# Required
af.api_key = 'XXXXXXXXXX'
af.api_secret = 'YYYYYYYYYY'
# Optional
af.default_country = 'nz' # default: nz
af.timeout = 10 # default: 10 seconds
af.retries = 12 # default: 12
af.retry_delay = 5 # default: 5 seconds
af.domain = 'yourdomain.com'
af.proxy_host = 'yourproxy.com'
af.proxy_port = 8080
af.proxy_user = 'username'
af.proxy_password = 'password'
end
Don't know your key and secret? Login to the AddressFinder portal to obtain your key and secret.
For Ruby on Rails:
The configure block is best placed in an initializer file (./config/initializers/addressfinder.rb
).
Usage
For available parameters and example responses, see the API documentation pages for New Zealand or Australia.
Address Verification
result = AddressFinder.cleanse(q: '186 Willis St, Wellington', country: 'nz')
if result
$stdout.puts "Success: #{result.postal}"
else
$stdout.puts "Sorry, can't find that address"
end
Address Autocomplete
begin
results = AddressFinder.address_search(q: '186 Willis Street')
if results.any?
$stdout.puts "Success: #{results}"
else
$stdout.puts "Sorry, there were no address matches"
end
rescue AddressFinder::RequestRejectedError => e
response = JSON.parse(e.body)
$stdout.puts response['message']
end
Address Metadata
begin
result = AddressFinder.address_info(pxid: '1-.B.3l')
if result
$stdout.puts "Success: #{result.a}"
else
$stdout.puts "Sorry, can't find that address"
end
rescue AddressFinder::RequestRejectedError => e
response = JSON.parse(e.body)
$stdout.puts response['message']
end
Location Autocomplete
begin
results = AddressFinder.location_search(q: 'Queen Street')
if results.any?
$stdout.puts "Success: #{results}"
else
$stdout.puts "Sorry, there were no location matches"
end
rescue AddressFinder::RequestRejectedError => e
response = JSON.parse(e.body)
$stdout.puts response['message']
end
Location Metadata
begin
result = AddressFinder.location_info(pxid: '1-.B.3l')
if result
$stdout.puts "Success: #{result.a}"
else
$stdout.puts "Sorry, can't find that location"
end
rescue AddressFinder::RequestRejectedError => e
response = JSON.parse(e.body)
$stdout.puts response['message']
end
Advanced Usage
Bulk Operations
If you have a series of API requests, you can use the bulk method to re-use the HTTP connection.
Note: The bulk method is currently only available for Address Verification (#cleanse
).
AddressFinder.bulk do |af|
CSV.foreach('auckland_addresses.csv') do |row|
result = af.cleanse(q: row[0], region_code: '1')
if result
$stdout.puts "Success: #{result.postal}"
else
$stdout.puts "Sorry, can't find that address"
end
end
end
Key and Secret override
What if you want to use another account for a specific query? You can override the api_key
and api_secret
.
begin
result = AddressFinder.address_info(pxid: '1-.B.3l', key: 'AAAAAAAAAAAAA', secret: 'BBBBBBBBBBBBB')
if result
$stdout.puts "Success: #{result.a}"
else
$stdout.puts "Sorry, can't find that address"
end
rescue AddressFinder::RequestRejectedError => e
response = JSON.parse(e.body)
$stdout.puts response['message']
end