0.01
A long-lived project that still receives updates
Ruby client library for Addressfinder
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

>= 1.0.0
>= 1.35
~> 3.7
~> 13.0
~> 3.11
~> 1.21

Runtime

 Project Readme

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.verification_version = 'v2' # default: v1
  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

New Zealand addresses

To verify a single New Zealand address, use the following method:

result = AddressFinder.address_verification(q: "186 Willis St, Wellington", country: "nz")

if result
  $stdout.puts "Success: '#{result.a}'"
else
  $stdout.puts "Sorry, can't find that address"
end

You can also verify a batch of New Zealand addresses using the following method. We suggest that you send up to 100 addresses in each batch.

addresses = ["186 Willis St, Wellington", "1 Ghuznee St, Te Aro, Wellington 6011", "bad address"]

results = AddressFinder.address_verification_nz_batch(addresses: addresses, concurrency: 10)

results.each_with_index do |result, index|
  if result
    $stdout.puts "Success: matched '#{addresses[index]}' with '#{result.a}'"
  else
    $stdout.puts "Sorry, can't find address: '#{addresses[index]}'"
  end
end

There is a demo of processing a CSV file of sample New Zealand address in the /demo/batch folder.

Australian addresses

To verify a single Australian address, use the following method:

result = AddressFinder.address_verification(q: '10/274 Harbour Drive, Coffs Harbour NSW 2450', gnaf: "1", country: 'au')

if result
  $stdout.puts "Success: #{result.full_address}"
else
  $stdout.puts "Sorry, can't find that address"
end

You can also verify a batch of Australian addresses using the following method: We suggest that you send up to 100 addresses in each batch.

addresses = ["10/274 Harbour Drive, Coffs Harbour NSW 2450", "49 CORNISH ST, COBAR NSW 2835", "bad address"]

results = AddressFinder.address_verification_au_batch(addresses: addresses, gnaf: "1", concurrency: 10)

results.each_with_index do |result, index|
  if result
    $stdout.puts "Success: matched '#{addresses[index]}' with '#{result.a}'"
  else
    $stdout.puts "Sorry, can't find address: '#{addresses[index]}'"
  end
end

There is a demo of processing a CSV file of sample Australian address in the /demo/batch folder.

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

Email Verification

This example shows how to request verification of a single email address.

begin
  result = AddressFinder.email_verification(email: 'john.doe', features: "domain,connection")
  $stdout.puts "This email address is verified: #{result.is_verified}"
rescue AddressFinder::RequestRejectedError => e
  response = JSON.parse(e.body)
  $stdout.puts response['message']
end

This example shows how to request verification of several email addresses:

emails = [
  "bert@myemail.com", 
  "charlish@myemail.com", 
  "support@addressfinder.com", 
  "bad-email-address"
]

results = AddressFinder.email_verification_batch(emails: emails, concurrency: 2, features: "provider,domain,connection")

results.each_with_index do |result, index|
  puts "Email: #{emails[index]} - #{result.is_verified ? "Verified" : "Unverified"}"
end

The emails will be verified concurrently, and returned in the same order in which they were provided.

Phone Verification

begin
  result = AddressFinder.phone_verification(phone_number: '1800 152 363', default_country_code: 'AU')
  $stdout.puts "This phone number is verified: #{result.is_verified}"
rescue AddressFinder::RequestRejectedError => e
  response = JSON.parse(e.body)
  $stdout.puts response['message']
end

Advanced Usage

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