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

Usage

Configuration

You should call the configure block on startup of your app. In a Ruby on Rails application this is normally performed in an initializer file. For example ./config/initializers/addressfinder.rb

AddressFinder.configure do |af|
  # Mandatory configuration
  af.api_key = 'XXXXXXXXXX'
  af.api_secret = 'YYYYYYYYYY'
  af.default_country = 'nz'

  # Optional configuration
  af.timeout = 10 # seconds
  af.proxy_host = 'corp.proxy.com'
  af.proxy_port = 8080
  af.proxy_user = 'username'
  af.proxy_password = 'password'
  af.domain = 'myserver.mycompany.co.nz'
end

You can obtain your API key and secret from the AddressFinder Portal.

Address Cleansing

See the documentation on the available parameters and expected response here:

https://addressfinder.nz/docs/address_cleanse_api/ https://addressfinder.com.au/docs/address_cleanse_api/

Usage example:

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

See documentation on the available parameters and expected response here:

https://addressfinder.nz/docs/location_api/

Usage example:

begin
  results = AddressFinder.location_search(q: 'Queen Street')
  if results.any?
    $standout.puts "Success: #{results}"
  else
    $standout.puts "Sorry, there were no location matches"
  end
rescue AddressFinder::RequestRejectedError => e
  response = JSON.parse(e.body)
  $standout.puts response['message']
end

Location Info

See documentation on the available parameters and expected response here:

https://addressfinder.nz/docs/location_info_api/

Usage example:

begin
  result = AddressFinder.location_info(pxid: '1-.B.3l')
  if result
    $standout.puts "Success: #{result.a}"
  else
    $standout.puts "Sorry, can't find that location"
  end
rescue AddressFinder::RequestRejectedError => e
  response = JSON.parse(e.body)
  $standout.puts response['message']
end

See documentation on the available parameters and expected response here:

https://addressfinder.nz/docs/address_api/

Usage example:

begin
  results = AddressFinder.address_search(q: '186 Willis Street')
  if results.any?
    $standout.puts "Success: #{results}"
  else
    $standout.puts "Sorry, there were no address matches"
  end
rescue AddressFinder::RequestRejectedError => e
  response = JSON.parse(e.body)
  $standout.puts response['message']
end

Address Info

See documentation on the available parameters and expected response here:

https://addressfinder.nz/docs/address_info_api/

Usage example:

begin
  result = AddressFinder.address_info(pxid: '1-.B.3l')
  if result
    $standout.puts "Success: #{result.a}"
  else
    $standout.puts "Sorry, can't find that address"
  end
rescue AddressFinder::RequestRejectedError => e
  response = JSON.parse(e.body)
  $standout.puts response['message']
end

Bulk Operations

If you have a series of calls you need to make to AddressFinder, you can use the bulk method which re-uses the HTTP connection.

The bulk method is only available for #cleanse operation.

Usage example:

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

Advanced Usage

Key and Secret Override

What if you want to use another acccount for a specific query using the AddressFinder gem in your ruby app?

You can override the api_key and api_secret set in the AddressFinder.configure block in ./config/initializers/addressfinder.rb when using the AddressFinder gem.

Those AddressFinder methods accept :key and :secret arguments:

  • #cleanse,
  • #location_search,
  • #location_info,
  • #address_search
  • #address_info

Usage example:

begin
  result = AddressFinder.address_info(pxid: '1-.B.3l', key: 'AAAAAAAAAAAAA', secret: 'BBBBBBBBBBBBB')
  if result
    $standout.puts "Success: #{result.a}"
  else
    $standout.puts "Sorry, can't find that address"
  end
rescue AddressFinder::RequestRejectedError => e
  response = JSON.parse(e.body)
  $standout.puts response['message']
end