Skip to content
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
lib
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

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 Search

The Address Search API supports the following address sets:

  • New Zealand addresses
  • Australian addresses from the GNAF dataset only
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 Autocomplete

The Address Autocomplete API supports the following address sets:

  • Australian addresses from the GNAF and PAF datasets only
begin
  results = AddressFinder.address_autocomplete(q: '275 high st, bel', au_paf: '1')
  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

Testing

You can run all the specs with the following command:

docker-compose up

You can guard for repeating test runs (while editing new code):

docker-compose run ruby bundle exec guard

You can’t perform that action at this time.