addressfinder 1.5.2 → 1.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 05ba956f56eb4abdf67174b1c8dc8fa60e429855
-  data.tar.gz: 473d3c098ab85f3255409d42fc114dbbddd278bf
+SHA256:
+  metadata.gz: a2191b3d7090b6eb2c2001f080427cc917c5af00262520c907b401a2a3d7c82e
+  data.tar.gz: bd35444c4cb2a31a47130ded4dae80596718a4d6998006ffc34b92512cf729dd
 SHA512:
-  metadata.gz: 9056caa0b3632c4069dc0f78fea84c876fa3fda0438af6cd771bee2a09aab93087e912decf5eabf923b442994360ec09c063f62d014ea86dd959be1dbf031082
-  data.tar.gz: 0d20f2503daaeed9e724231973414731e65bfa4aa468f37ad7dadd059b226832bdf0f1ac3eadd49fbc395dc746cf5887e092e98691e9aa09ff4473764c1cba24
+  metadata.gz: '08384b27d66dd5397f8e07dc550b86ea0befa4eaae6f8f294dcb8f01e4372739bebfe0484a6874fd0f3f05b6f19ed21108e7923fd8416379532d5b799bb5c60f'
+  data.tar.gz: aadab0cc138ef723af46bd2e6baf1ac6571f51ecaba2dcfa2aedd34ff44b3a5c44b78f39ca5c2828edea29ae3329f1e22ec8ddfdc787482c24142202ece4b749

data/.travis.yml

@@ -1,4 +1,6 @@
 language: ruby
 rvm:
-  - 2.1.2
-  - 2.2.3
+  - 2.2.7
+  - 2.3.1
+  - 2.4.1
+  - 2.6.3

data/CHANGELOG.md

@@ -1,3 +1,24 @@
+# AddressFinder 1.7.1 (June 2, 2021) #
+
+* Add support for PAF verification
+* Rename cleanse to verification
+
+# AddressFinder 1.7.0 (May 4, 2020) #
+
+* Add support for Address Autocomplete API (Australia only)
+
+# AddressFinder 1.6.2 (September 23, 2019) #
+
+* Add support for an optional state_codes parameter in the Cleanse class
+
+# AddressFinder 1.6.1 (January 14, 2019) #
+
+* Add support for an optional census parameter in the Cleanse class
+
+# AddressFinder 1.6.0 (August 10, 2017) #
+
+* Add support for a configurable number of request retries
+
 # AddressFinder 1.5.2 (December 21, 2015) #
 
 * Update for the nested response format used in Address Cleanse Australia

data/Dockerfile

@@ -0,0 +1,28 @@
+# Use the barebones version of Ruby 2.6.1
+FROM ruby:2.6
+
+# Install dependencies:
+# - build-essential: To ensure certain gems can be compiled
+# - nodejs: Compile assets
+# - bundler: ensure most recent version is installed
+RUN apt-get update && apt-get install -qq -y build-essential --fix-missing --no-install-recommends
+RUN gem install bundler
+
+# Set an environment variable to store where the app is installed to inside
+# of the Docker image.
+ENV LANG C.UTF-8
+ENV BUNDLE_PATH /bundle
+ENV INSTALL_PATH /addressfinder-ruby
+RUN mkdir -p $INSTALL_PATH
+
+# Create address verification directories
+RUN mkdir -p $INSTALL_PATH/verification/originals
+RUN mkdir -p $INSTALL_PATH/verification/verified
+
+# This sets the context of where commands will be ran in and is documented
+# on Docker's website extensively.
+WORKDIR $INSTALL_PATH
+
+ADD . $INSTALL_PATH
+
+RUN bundle install

data/Guardfile

@@ -1,4 +1,4 @@
-guard :rspec, cmd: 'rspec' do
+guard :rspec, cmd: 'bundle exec rspec' do
   watch(%r{^spec/.+_spec\.rb$})
   watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
   watch('spec/spec_helper.rb')  { "spec" }

data/LICENSE.md

@@ -0,0 +1,15 @@
+Copyright (c) 2015-present AddressFinder
+
+The intellectual property rights in this plugin are owned by AddressFinder Limited of Wellington New Zealand (referred to below as “we”, “us” or “our”) or its third party licensors.  The plugin may be accessed and used by AddressFinder customers only, subject to the following terms. If you are not, or are no longer, an AddressFinder customer you are not permitted to access or use the plugin in any way.
+
+If you are an AddressFinder customer (referred to below as “you” or “your”), the following terms apply in relation to your access and use of the plugin (and your access or use of the plugin confirms your acceptance of the following terms). If you do not accept the following terms you are not permitted to access or use the plugin in any way.
+* In these terms, “Terms and Conditions” means the applicable Terms and Conditions that you entered into, being either https://addressfinder.nz/legal/terms/ or https://addressfinder.com.au/legal/terms/, and “Services” and “Subscription Term” have the meaning given in the Terms and Conditions.
+* All rights, title and interest (including, without limitation, all intellectual property rights) in and to the plugin are owned by us or our third party licensors. Provided that you comply with these terms, and the Terms and Conditions, we grant you the right during your Subscription Term to: (a) access and use the plugin solely in connection with the Services and then only in combination with websites that you own or control; and (b) view the source code and configurations of the plugin solely for the purpose of evaluating the plugin in relation to its use in connection with the Services, and for no other purpose. This right is non-exclusive, non-transferable and may be revoked by us at any time. You are not granted any other rights or licences in relation to the plugin.
+* You must never copy, modify, publish, merge, distribute, resell, lease, transfer or sub-license, or create derivative works from, all or any part of the plugin. You must never access or use the plugin for any purpose related to building a product or service which competes with the Services or the plugin or has similar features or functionality. You must comply with all instructions or restrictions that we provide to you in relation to the plugin (including, without limitation, that we may post on this page from time to time).
+* The plugin is provided to you on an "as is" and "as available" basis and your use of it is at your sole risk. To the maximum extent permitted by law, we do not represent or warrant that the plugin will be secure, reliable, uninterrupted, always available, free of errors, omissions, inaccuracies, viruses or other destructive code, or that it will be fit for your purposes or for use in any specific technical environment or that any problems can or will be corrected. To the maximum extent permitted by law, we give no warranties in relation to the plugin. To avoid doubt, to the maximum extent permitted by law, we disclaim and exclude all implied representations, warranties and conditions (including any warranties of fitness for purpose, merchantability, title and non-infringement). Certain legislation may imply warranties or conditions, impose obligations or give statutory guarantees (together, Statutory Provisions) which cannot be excluded, restricted or modified except to a limited extent. These terms must be read subject to applicable Statutory Provisions. If the Statutory Provisions apply, notwithstanding any other provision of these terms, to the extent to which we are entitled to do so, we limit our liability in respect of any claim to: (a) in the case of goods, at our option: the replacement of the goods or the supply of equivalent goods; the repair of the goods; the payment of the cost of replacing the goods or acquiring equivalent goods; or the payment of having the goods repaired; and (b) in the case of services, at our option: the supply of the services again; or the payment of the cost of having the services supplied again. If you entered into our New Zealand Terms and Conditions, you represent to us that you are acquiring the right to use the plugin for the purposes of a business and so you agree that the provisions of the Consumer Guarantees Act 1993 do not apply to the plugin.
+* To the maximum extent permitted by law, we and Our Related Parties will not be liable to you or any third party for any loss or damage to data, breach of security, loss of profit, revenue, opportunity or saving, or any incidental, indirect, special or consequential loss or damage. To the maximum extent permitted by law, the total aggregate liability of us and Our Related Parties (together) to you under or in connection with these terms or its subject matter is limited to NZ$10. These limitations and exclusions of liability apply however liability arises, whether in contract, in tort (including negligence), for breach of statutory duty or otherwise.  You fully indemnify us from and against any claim, proceeding, damage, loss, liability, cost or expense (including legal costs on a solicitor and own client basis) arising from or connected to your use of plugin or breach of these terms. In these terms “Our Related Parties” means AddressFinder Pty Limited, ACN 606 672 333, any related company of us or AddressFinder Pty Limited (where “related company” has the meaning given in section 2(3) of the Companies Act 1993, and includes any company or similar entity which would be a related company within that definition if incorporated as a company in New Zealand) and our suppliers, contractors, directors, employees and agents.
+* We may change these terms at any time by emailing you, by updating the Terms and Conditions and/or by displaying or referring to the replacement terms on this page.  Your continued use of the plugin after you receive notice of any such changes will amount to your acceptance of those changes. If you don’t accept those changes you must immediately stop using the plugin.
+* Any waiver of any part of these terms must be in writing and signed by one of our authorised representatives. Any delay or failure by us to exercise any right does not prevent us from exercising that right, or any other right, on that or any other occasion.
+* Any unlawful or unenforceable provision of these terms will be deemed to be amended to the minimum extent necessary to ensure that it is not unlawful or unenforceable and, as far as is possible, to ensure that it is consistent with the intent and effect of the provision.  The remaining provisions will be enforceable as if such unlawful or unenforceable provision had not been included in these terms.  If the provision is unable to be amended without materially altering the intent and effect of the provision, it will be severed, and the remaining provisions will be enforceable.
+* The terms are governed by the laws of New Zealand and you and we submit to the non-exclusive jurisdiction of the New Zealand courts.
+

data/README.md

@@ -1,9 +1,9 @@
 # AddressFinder Ruby Gem
 
 [![Gem Version](https://badge.fury.io/rb/addressfinder.svg)](http://badge.fury.io/rb/addressfinder)
-[![Build  Status](https://travis-ci.org/AbleTech/addressfinder-ruby.svg)](https://travis-ci.org/AbleTech/addressfinder-ruby)
+[![Build  Status](https://travis-ci.com/github/AddressFinder/addressfinder-ruby.svg)](https://travis-ci.com/github/AddressFinder/addressfinder-ruby)
 
-A client library for accessing the AddressFinder APIs.
+A client library for accessing the [AddressFinder](https://addressfinder.nz/?utm_source=github&utm_medium=readme&utm_campaign=addressfinder_rubygem&utm_term=AddressFinder) APIs.
 
 ## Installation
 
@@ -19,43 +19,44 @@ Or install it yourself as:
 
     $ gem install addressfinder
 
-## Usage
-
-### Configuration
+## 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`
+Use the configure block to set your `api_key` and `api_secret`.
 
 ```ruby
 AddressFinder.configure do |af|
-  # Mandatory configuration
+  # Required
   af.api_key = 'XXXXXXXXXX'
   af.api_secret = 'YYYYYYYYYY'
-  af.default_country = 'nz'
 
-  # Optional configuration
-  af.timeout = 10 # seconds
-  af.proxy_host = 'corp.proxy.com'
+  # 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'
-  af.domain = 'myserver.mycompany.co.nz'
 end
 ```
 
-You can obtain your API key and secret from the AddressFinder Portal.
+**_Don't know your key and secret?_**
+*Login to the [AddressFinder portal](https://portal.addressfinder.io/?utm_source=github&utm_medium=readme&utm_campaign=addressfinder_rubygem&utm_term=AddressFinder%20Portal) to obtain your key and secret.*
 
-### Address Cleansing
+**_For Ruby on Rails:_**
+*The configure block is best placed in an initializer file (`./config/initializers/addressfinder.rb`).*
 
-See the documentation on the available parameters and expected response here:
+## Usage
 
-https://addressfinder.nz/docs/address_cleanse_api/
-https://addressfinder.com.au/docs/address_cleanse_api/
+For available parameters and example responses, see the API documentation pages for [New Zealand](https://addressfinder.nz/docs?utm_source=github&utm_medium=readme&utm_campaign=addressfinder_rubygem&utm_term=New%20Zealand) or [Australia](https://addressfinder.com.au/docs?utm_source=github&utm_medium=readme&utm_campaign=addressfinder_rubygem&utm_term=Australia).
 
-Usage example:
+
+#### Address Verification
 
 ```ruby
-result = AddressFinder.cleanse(q: '186 Willis St, Wellington', country: 'nz')
+result = AddressFinder.verification(q: '186 Willis St, Wellington', country: 'nz')
 
 if result
   $stdout.puts "Success: #{result.postal}"
@@ -64,107 +65,110 @@ else
 end
 ```
 
-### Location Search
+**Note:** The deprecated method `cleanse` is still available now but will be dropped in the future.
 
-See documentation on the available parameters and expected response here:
+#### Address Search
 
-https://addressfinder.nz/docs/location_api/
+The Address Search API supports the following address sets:
 
-Usage example:
+* New Zealand addresses
+* Australian addresses from the GNAF dataset only
 
 ```ruby
 begin
-  results = AddressFinder.location_search(q: 'Queen Street')
+  results = AddressFinder.address_search(q: '186 Willis Street')
   if results.any?
-    $standout.puts "Success: #{results}"
+    $stdout.puts "Success: #{results}"
   else
-    $standout.puts "Sorry, there were no location matches"
+    $stdout.puts "Sorry, there were no address matches"
   end
 rescue AddressFinder::RequestRejectedError => e
   response = JSON.parse(e.body)
-  $standout.puts response['message']
+  $stdout.puts response['message']
 end
 ```
 
-### Location Info
-
-See documentation on the available parameters and expected response here:
+#### Address Autocomplete
 
-https://addressfinder.nz/docs/location_info_api/
+The Address Autocomplete API supports the following address sets:
 
-Usage example:
+* Australian addresses from the GNAF and PAF datasets only
 
 ```ruby
 begin
-  result = AddressFinder.location_info(pxid: '1-.B.3l')
-  if result
-    $standout.puts "Success: #{result.a}"
+  results = AddressFinder.address_autocomplete(q: '275 high st, bel', au_paf: '1')
+  if results.any?
+    $stdout.puts "Success: #{results}"
   else
-    $standout.puts "Sorry, can't find that location"
+    $stdout.puts "Sorry, there were no address matches"
   end
 rescue AddressFinder::RequestRejectedError => e
   response = JSON.parse(e.body)
-  $standout.puts response['message']
+  $stdout.puts response['message']
 end
 ```
 
-### Address Search
+#### Address Metadata
 
-See documentation on the available parameters and expected response here:
-
-https://addressfinder.nz/docs/address_api/
+```ruby
+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
+```
 
-Usage example:
+#### Location Autocomplete
 
 ```ruby
 begin
-  results = AddressFinder.address_search(q: '186 Willis Street')
+  results = AddressFinder.location_search(q: 'Queen Street')
   if results.any?
-    $standout.puts "Success: #{results}"
+    $stdout.puts "Success: #{results}"
   else
-    $standout.puts "Sorry, there were no address matches"
+    $stdout.puts "Sorry, there were no location matches"
   end
 rescue AddressFinder::RequestRejectedError => e
   response = JSON.parse(e.body)
-  $standout.puts response['message']
+  $stdout.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:
+#### Location Metadata
 
 ```ruby
 begin
-  result = AddressFinder.address_info(pxid: '1-.B.3l')
+  result = AddressFinder.location_info(pxid: '1-.B.3l')
   if result
-    $standout.puts "Success: #{result.a}"
+    $stdout.puts "Success: #{result.a}"
   else
-    $standout.puts "Sorry, can't find that address"
+    $stdout.puts "Sorry, can't find that location"
   end
 rescue AddressFinder::RequestRejectedError => e
   response = JSON.parse(e.body)
-  $standout.puts response['message']
+  $stdout.puts response['message']
 end
 ```
 
-### Bulk Operations
+## Advanced Usage
 
-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.
+#### Bulk Operations
 
-The bulk method is only available for #cleanse operation.
+If you have a series of API requests, you can use the
+bulk method to re-use the HTTP connection.
 
-Usage example:
+**Note:** The bulk method is currently only available for Address Verification (`#verification`).
 
 ```ruby
 AddressFinder.bulk do |af|
   CSV.foreach('auckland_addresses.csv') do |row|
-    result = af.cleanse(q: row[0], region_code: '1')
+    result = af.verification(q: row[0], region_code: '1')
 
     if result
       $stdout.puts "Success: #{result.postal}"
@@ -175,34 +179,31 @@ AddressFinder.bulk do |af|
 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`
+#### Key and Secret override
 
-Usage example:
+What if you want to use another account for a specific query? You can override the `api_key` and `api_secret`.
 
 ```ruby
 begin
   result = AddressFinder.address_info(pxid: '1-.B.3l', key: 'AAAAAAAAAAAAA', secret: 'BBBBBBBBBBBBB')
   if result
-    $standout.puts "Success: #{result.a}"
+    $stdout.puts "Success: #{result.a}"
   else
-    $standout.puts "Sorry, can't find that address"
+    $stdout.puts "Sorry, can't find that address"
   end
 rescue AddressFinder::RequestRejectedError => e
   response = JSON.parse(e.body)
-  $standout.puts response['message']
+  $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`

data/addressfinder.gemspec

@@ -5,11 +5,11 @@ Gem::Specification.new do |gem|
   gem.name          = "addressfinder"
   gem.version       = AddressFinder::VERSION
   gem.licenses      = ['MIT']
-  gem.authors       = ["Nigel Ramsay", "Naiki Pohe", "Sean Arnold", "Alexandre Barret"]
-  gem.email         = ["nigel.ramsay@abletech.co.nz", "naiki.pohe@abletech.co.nz", "seanarnie@gmail.com", "alex@abletech.nz"]
+  gem.authors       = ["Nigel Ramsay", "Naiki Pohe", "Sean Arnold", "Alexandre Barret", "Cassandre Guinut"]
+  gem.email         = ["nigel.ramsay@addressfinder.nz", "naiki.pohe@abletech.co.nz", "seanarnie@gmail.com", "alex@abletech.nz", "cassandre.guinut@addressfinder.nz"]
   gem.description   = %q{Ruby client library for AddressFinder}
   gem.summary       = %q{Provides easy access to AddressFinder APIs}
-  gem.homepage      = "https://github.com/AbleTech/addressfinder-ruby"
+  gem.homepage      = "https://github.com/AddressFinder/addressfinder-ruby"
 
   gem.files         = `git ls-files`.split($/)
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
@@ -20,6 +20,7 @@ Gem::Specification.new do |gem|
   gem.add_dependency 'multi_json', '~> 1.11'
   gem.add_development_dependency 'rspec', '~> 3.3'
   gem.add_development_dependency 'guard-rspec', '~> 4.6'
-  gem.add_development_dependency 'rake', '~> 10.4'
+  gem.add_development_dependency 'rake', '~> 13.0'
   gem.add_development_dependency 'webmock', '~> 1.21'
+  gem.add_development_dependency 'listen', '~> 3.2'
 end

data/docker-compose.yml

@@ -0,0 +1,11 @@
+version: '3'
+services:
+  ruby:
+    build: .
+    volumes:
+      - .:/addressfinder-ruby
+      - bundle-cache:/bundle
+    command: bundle exec rspec
+
+volumes:
+  bundle-cache: {}

data/lib/addressfinder.rb

@@ -1,15 +1,16 @@
-require 'net/http'
 require 'multi_json'
 require 'addressfinder/version'
 require 'addressfinder/configuration'
-require 'addressfinder/cleanse'
+require 'addressfinder/verification'
 require 'addressfinder/location_info'
 require 'addressfinder/location_search'
 require 'addressfinder/address_info'
 require 'addressfinder/address_search'
+require 'addressfinder/address_autocomplete'
 require 'addressfinder/bulk'
 require 'addressfinder/errors'
 require 'addressfinder/util'
+require 'addressfinder/http'
 
 module AddressFinder
   class << self
@@ -27,42 +28,36 @@ module AddressFinder
       @configuration ||= AddressFinder::Configuration.new
     end
 
-    def cleanse(args={})
-      AddressFinder::Cleanse.new(args.merge(http: configure_http)).perform.result
+    def cleanse(args={}) # We are keeping this method for backward compatibility
+      AddressFinder::Verification.new(args.merge(http: AddressFinder::HTTP.new(configuration))).perform.result
+    end
+
+    def verification(args={})
+      AddressFinder::Verification.new(args.merge(http: AddressFinder::HTTP.new(configuration))).perform.result
     end
 
     def location_search(args={})
-      AddressFinder::LocationSearch.new(params: args, http: configure_http).perform.results
+      AddressFinder::LocationSearch.new(params: args, http: AddressFinder::HTTP.new(configuration)).perform.results
     end
 
     def location_info(args={})
-      AddressFinder::LocationInfo.new(params: args, http: configure_http).perform.result
+      AddressFinder::LocationInfo.new(params: args, http: AddressFinder::HTTP.new(configuration)).perform.result
     end
 
     def address_search(args={})
-      AddressFinder::AddressSearch.new(params: args, http: configure_http).perform.results
+      AddressFinder::AddressSearch.new(params: args, http: AddressFinder::HTTP.new(configuration)).perform.results
     end
 
-    def address_info(args={})
-      AddressFinder::AddressInfo.new(params: args, http: configure_http).perform.result
+    def address_autocomplete(args={})
+      AddressFinder::AddressAutocomplete.new(params: args, http: AddressFinder::HTTP.new(configuration)).perform.results
     end
 
-    def bulk(&block)
-      # TODO include parameter http: configure_http
-      AddressFinder::Bulk.new(&block).perform
+    def address_info(args={})
+      AddressFinder::AddressInfo.new(params: args, http: AddressFinder::HTTP.new(configuration)).perform.result
     end
 
-    private
-
-    def configure_http
-      http = Net::HTTP.new(configuration.hostname, configuration.port,
-                           configuration.proxy_host, configuration.proxy_port,
-                           configuration.proxy_user, configuration.proxy_password)
-      http.open_timeout = configuration.timeout
-      http.read_timeout = configuration.timeout
-      http.use_ssl = true
-
-      http
+    def bulk(&block)
+      AddressFinder::Bulk.new(http: AddressFinder::HTTP.new(configuration), &block).perform
     end
   end
 end