Ruby client gem for AddressFinder
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
spec
.gitignore
.travis.yml
CHANGELOG.md
Gemfile
Guardfile
LICENSE
README.md
Rakefile
addressfinder.gemspec

README.md

AddressFinder Ruby Gem

Gem Version Build  Status

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