abn_search 0.0.3 → 0.0.5

data/README.rdoc

@@ -1,29 +1,38 @@
+=== Important: Gem has been updated to support searching the Australian Business Registry (ABR) by name as well as abn. The syntax to call and validate ABN's has changed!
+
 A simple ABN search library for validating and obtaining ABN details from the Australian Business Register.
 
 PLEASE NOTE: You will need a GUID to be able to use the ABR business lookup API. You can obtain one at the following link;
 http://www.abr.business.gov.au/Register.aspx
 
-= Rails 3 Installation
+= Rails 3+ Installation
 
 Simply add the following line to your Gemfile and run bundle install.
 
   gem 'abn_search'
-    
+
 = Usage
 
   require 'abn_search'
 
-  abn = ABNSearch.new("34355893198", "YOUR_GUID_HERE")
-  => #<ABNSearch:0x0000010109bc38 @errors=[], @abn="34355893198", @WSDL_URL="http://abr.business.gov.au/ABRXMLSearch/AbrXmlSearch.asmx/ABRSearchByABN?", @ABN_LOOKUP_GUID="ac60a98a-fe5e-4a4a-bfcc-bcf30a51e1a9", @name="sony", @entity_type="IND Individual/Sole Trader"> 
-  
-  puts abn.name
-   => "sony"
-       
-  puts abn.entity_type
-  => "IND Individual/Sole Trader"  
-    
-  abn.valid?
-  => true
+  # Search by ABN Number
+  abn = ABNSearch.new("YOUR_GUID_HERE")
+  result = abn.search("59001215354")
+  => {:abn=>"59001215354", :entity_type=>"Australian Public Company", :status=>"Active", :main_name=>"SONY AUSTRALIA LIMITED", :trading_name=>"", :legal_name=>"", :other_trading_name=>"", :name=>"SONY AUSTRALIA LIMITED"}
+
+  puts result[:entity_type]
+  => "Australian Public Company"
+
+  puts result[:status]
+  => "Active"
+
+  puts result[:name]
+  => "SONY AUSTRALIA LIMITED"
+
+  # Search by name
+  results = abn.search_by_name("Sony", ['NSW'], '2000')
+
+  puts results
 
 = Errors
 If an ABN is missing, invalid or expired - check the errors attribute.

data/abn_search.gemspec

@@ -3,7 +3,7 @@ $:.push File.expand_path("../lib", __FILE__)
 
 Gem::Specification.new do |s|
   s.name        = "abn_search"
-  s.version     = '0.0.3'
+  s.version     = '0.0.5'
   s.authors     = ["James Martin"]
   s.email       = ["james@visualconnect.net"]
   s.homepage    = "https://github.com/jamsi/abn_search"
@@ -16,5 +16,7 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
 
+  s.add_dependency("savon")
   s.add_dependency("nokogiri")
+  s.add_development_dependency("yard")
 end

data/lib/abn_search.rb

@@ -1,59 +1,128 @@
-require 'nokogiri'
-require 'open-uri'
+#
+# ABN Search
+#
+# Request examples;
+#
+# Search by ABN number
+# > a = ABNSearch.new("your-guid")
+# > result = a.search("56206894472")
+#
+# Search by name and return an array of results
+# > a = ABNSearch.new("your-guid")
+# > result = a.search_by_name("Sony", ['NSW', 'VIC'])
+#
+
+require 'savon'
 
 class ABNSearch
 
   module Version
-    VERSION = "0.0.3"
+    VERSION = "0.0.5"
   end
 
-  attr_accessor :name, :abn, :entity_type, :errors, :guid
+  attr_accessor :errors, :guid, :proxy, :client_options
 
-  def initialize(abn=nil, guid=nil)
+  # Setup a new instance of the ABN search class.
+  #
+  # @param [String] guid - the ABR GUID for Web Services access
+  # @param [Hash] options - options detailed below
+  # @option options [String] :proxy Proxy URL string if required (Example: http://user:pass@host.example.com:443)
+  # @return [ABNSearch]
+  #
+  def initialize(guid=nil, options = {})
     self.errors = []
-    self.abn = abn unless abn.nil?
     self.guid = guid unless guid.nil?
-    self.name = "n/a"
-    self.search
+    self.proxy = options[:proxy] || nil
+    self.client_options = {}
+    self.client_options = { :wsdl => "http://www.abn.business.gov.au/abrxmlsearch/ABRXMLSearch.asmx?WSDL" }
+    self.client_options.merge!({ :proxy => self.proxy }) unless self.proxy.nil?
   end
 
-  def search
-    self.errors << "No ABN provided." && return if self.abn.nil?
+  # Performs an ABR search for the ABN setup upon initialization
+  #
+  # @param [String] abn - the abn you wish to search for
+  # @return [ABNSearch] search results in class instance
+  def search(abn)
+    self.errors << "No ABN provided." && return if abn.nil?
     self.errors << "No GUID provided. Please obtain one at - http://www.abr.business.gov.au/Webservices.aspx" && return if self.guid.nil?
 
-    @WSDL_URL = 'http://abr.business.gov.au/ABRXMLSearch/AbrXmlSearch.asmx/ABRSearchByABN?'
-    url = @WSDL_URL + "searchString=#{self.abn}&includeHistoricalDetails=n&authenticationGuid=#{self.guid}"
-    doc = Nokogiri::HTML(open(url))
-
-    # Fetch attributes we require
-    base_path = '//html/body/abrpayloadsearchresults/response/businessentity'
-    entity_type = doc.xpath(base_path + '/entitytype')
-    abn = doc.xpath(base_path + '/abn/identifiervalue')
-    trading_name = doc.xpath(base_path + '/maintradingname/organisationname')
-    main_name = doc.xpath(base_path + '/mainname/organisationname')
-    expires = doc.xpath(base_path + '/entitystatus/entitystatuscode')
-
-    # Did we find a valid ABN?
-    if abn[0].nil?
-      self.errors << "Invalid ABN number."
-      return
+    begin
+      client = Savon.client(self.client_options)
+
+      response = client.call(:abr_search_by_abn, message: { authenticationGuid: self.guid, searchString: abn.gsub(" ", ""), includeHistoricalDetails: "N" })
+      result = response.body[:abr_search_by_abn_response][:abr_payload_search_results][:response][:business_entity]
+      return parse_search_result(result)
+    rescue => ex
+      self.errors << ex.to_s
     end
+  end
+
+  # Searches the ABR registry by name. Simply pass in the search term and which state(s) to search in.
+  #
+  # @param [String] name - the search term
+  # @param [Array] states - a list of states that you wish to filter by
+  # @param [String] postcode - the postcode you wish to filter by
+  def search_by_name(name, states=['NSW'], postcode='ALL')
 
-    # Is the busines still valid?
-    if expires && expires[0].content.include?("Cancelled")
-      self.errors << "Business ABN #{self.abn} has expired."
-      return
+    begin
+      client = Savon.client(self.client_options)
+      request = {
+        externalNameSearch: {
+          authenticationGuid: self.guid, name: name,
+          filters: {
+            nameType: {
+              tradingName: 'Y', legalName: 'Y'
+            },
+            postcode: postcode,
+            "stateCode" => {
+              'QLD' => states.include?('QLD') ? "Y" : "N",
+              'NT' => states.include?('NT') ? "Y" : "N",
+              'SA' => states.include?('SA') ? "Y" : "N",
+              'WA' => states.include?('WA') ? "Y" : "N",
+              'VIC' => states.include?('VIC') ? "Y" : "N",
+              'ACT' => states.include?('ACT') ? "Y" : "N",
+              'TAS' => states.include?('TAS') ? "Y" : "N",
+              'NSW' => states.include?('NSW') ? "Y" : "N"
+            }
+          }
+        },
+        authenticationGuid: self.guid
+      }
+
+      response = client.call(:abr_search_by_name, message: request)
+      results = response.body[:abr_search_by_name_response][:abr_payload_search_results][:response][:search_results_list][:search_results_record]
+
+      return [parse_search_result(results)] if !results.is_a?(Array)
+      return results.map do |r| parse_search_result(r) end
+    rescue => ex
+      self.errors << ex.to_s
     end
+  end
 
-    # Set ABN business attributes
-    self.entity_type = entity_type[0].content unless entity_type[0].nil?
+  # Parses results for a search by ABN
+  def parse_search_result(result)
+    result = {
+      abn:            result[:abn][:identifier_value],
+      entity_type:    result[:entity_type].blank? ? "" : result[:entity_type][:entity_description],
+      status:         result[:entity_status].blank? ? "" : result[:entity_status][:entity_status_code],
+      main_name:      result[:main_name].blank? ? "" : result[:main_name][:organisation_name],
+      trading_name:   result[:main_trading_name].blank? ? "" : result[:main_trading_name][:organisation_name],
+      legal_name:     result[:legal_name].blank? ? "" : "#{result[:legal_name][:given_name]} #{result[:legal_name][:family_name]}",
+      other_trading_name: result[:other_trading_name].blank? ? "" : result[:other_trading_name][:organisation_name]
+    }
 
-    # Set the business name. Sometimes there's no trading name .. but a "main name".
-    if trading_name[0].nil?
-      self.name = main_name[0].content if !main_name.empty?
+    # Work out what we should return as a name
+    if !result[:trading_name].blank?
+      result[:name] = result[:trading_name]
+    elsif !result[:main_name].blank?
+      result[:name] = result[:main_name]
+    elsif !result[:other_trading_name].blank?
+      result[:name] = result[:other_trading_name]
     else
-      self.name = trading_name[0].content if !trading_name.empty?
+      result[:name] = result[:legal_name]
     end
+
+    return result
   end
 
   def valid?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: abn_search
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,27 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-01-24 00:00:00.000000000Z
+date: 2013-07-08 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: savon
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: nokogiri
-  requirement: &2157861680 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,7 +37,28 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2157861680
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A simple ABN search library for validating and obtaining ABN details
   from the Australian Business Register.
 email:
@@ -56,9 +93,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: abn_search
-rubygems_version: 1.8.11
+rubygems_version: 1.8.25
 signing_key: 
 specification_version: 3
 summary: ABNSearch library for Australian businesses.
 test_files: []
-has_rdoc: