mcmire-address_standardization 0.2.0

data/README.rdoc

@@ -0,0 +1,76 @@
+= address_standardization
+
+== Summary
+
+A tiny Ruby library to quickly standardize a postal address. Right now this supports Google Maps and MelissaData.
+
+== Installation
+
+Put this in your environment.rb:
+
+  config.gem 'mcmire-address_standardization', :lib => "address_standardization", :source => "http://gems.github.com"
+
+Then run <tt>rake gems:install</tt> to install the gem.
+
+== Usage
+
+Right now there are two methods supported: MelissaData and Google Maps.
+
+MelissaData provides two services: {US address lookup}[http://www.melissadata.com/lookups/AddressVerify.asp] and {Canadian address lookup}[http://www.melissadata.com/lookups/CanadianAddressVerify.asp]. They both work the same way, however. First, here's how to standardize a US address:
+
+  addr = AddressStandardization::MelissaData::USAddress.standardize(
+    :street => "1 Infinite Loop",
+    :city => "Cupertino",
+    :state => "CA"
+  )
+  
+This submits the address to MelissaData. If the address can't be found, you'll get back +nil+. But if the address can be found (as in this case), you'll get an instance of <tt>AddressStandardization::MelissaData::USAddress</tt>. If you store the instance, you can refer to the individual fields like so:
+
+  addr.street  #=> "1 INFINITE LOOP"
+  addr.city    #=> "CUPERTINO"
+  addr.state   #=> "CA"
+  addr.zip     #=> "95014-2083"
+
+And standardizing a Canadian address:
+
+  addr = AddressStandardization::MelissaData::CanadianAddress.standardize(
+    :street => "103 Metig St",
+    :city => "Sault Ste Marie",
+    :province => "ON"
+  )
+  addr.street      #=> "103 METIG ST RR 4"
+  addr.city        #=> "SAULT STE MARIE"
+  addr.province    #=> "ON"
+  addr.postalcode  #=> "P6A 5K9"
+
+Using Google Maps to validate an address is just as easy:
+
+  addr = AddressStandardization::GoogleMaps::Address.standardize(
+    :street => "1600 Amphitheatre Parkway",
+    :city => "Mountain View",
+    :state => "CA"
+  )
+  addr.street     #=> "1600 AMPHITHEATRE PKWY"
+  addr.city       #=> "MOUNTAIN VIEW"
+  addr.state      #=> "CA"
+  addr.zip        #=> "94043"
+  addr.country    #=> "USA"
+  
+And, again, a Canadian address:
+
+  addr = AddressStandardization::GoogleMaps::Address.standardize(
+    :street => "1770 Stenson Blvd.",
+    :city => "Peterborough",
+    :province => "ON"
+  )
+  addr.street      #=> "1770 STENSON BLVD"
+  addr.city        #=> "PETERBOROUGH"
+  addr.province    #=> "ON"
+  addr.postalcode  #=> "K9K"
+  addr.country     #=> "CANADA"
+
+You'll notice that for some reason, the Google Maps API doesn't return the full postal code for Canadian addresses. If you know why this is please let me know (my email address is below).
+
+== Author
+
+(c) 2008 Elliot Winkler (elliot dot winkler at gmail dot com). Released under the MIT license.

data/Rakefile

@@ -0,0 +1,40 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'rake/testtask'
+
+require 'lib/address_standardization/version'
+
+task :default => :test
+
+spec = Gem::Specification.new do |s|
+  s.name             = 'address_standardization'
+  s.version          = AddressStandardization::Version.to_s
+  s.has_rdoc         = true
+  s.extra_rdoc_files = %w(README.rdoc)
+  s.rdoc_options     = %w(--main README.rdoc)
+  s.summary          = "A tiny Ruby library to quickly standardize a postal address"
+  s.author           = 'Elliot Winkler'
+  s.email            = 'elliot.winkler@gmail.com'
+  s.homepage         = 'http://github.com/mcmire/address_standardization'
+  s.files            = %w(README.rdoc Rakefile) + Dir.glob("{lib,test}/**/*")
+  # s.executables    = ['address_standardization']
+  
+  s.add_dependency('mechanize')
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+desc 'Generate the gemspec to serve this Gem from Github'
+task :github do
+  file = File.dirname(__FILE__) + "/#{spec.name}.gemspec"
+  File.open(file, 'w') {|f| f << spec.to_ruby }
+  puts "Created gemspec: #{file}"
+end

data/lib/address_standardization.rb

@@ -0,0 +1,9 @@
+# address_standardization: A tiny Ruby library to quickly standardize a postal address
+# Copyright (C) 2008 Elliot Winkler. Released under the MIT license.
+
+require File.dirname(__FILE__)+'/address_standardization/ruby_ext'
+require File.dirname(__FILE__)+'/address_standardization/class_level_inheritable_attributes'
+
+require File.dirname(__FILE__)+'/address_standardization/abstract_address'
+require File.dirname(__FILE__)+'/address_standardization/melissa_data'
+require File.dirname(__FILE__)+'/address_standardization/google_maps'

data/lib/address_standardization/abstract_address.rb

@@ -0,0 +1,58 @@
+module AddressStandardization
+  class StandardizationError < StandardError; end
+  
+  class AbstractAddress
+    
+    include ClassLevelInheritableAttributes
+    inheritable_attributes :valid_keys
+      
+    def self.standardize
+      raise NotImplementedError, "You must override .standardize in a subclass"
+    end
+    
+    attr_reader :address_info
+  
+    def initialize(address_info)
+      raise NotImplementedError, "You must define valid_keys" unless self.class.valid_keys
+      raise ArgumentError, "No address given!" if address_info.empty?
+      address_info = address_info.inject({}) {|h,(k,v)| h[k.to_s] = v; h }  # stringify keys
+      validate_keys(address_info)
+      standardize_values!(address_info)
+      @address_info = address_info
+    end
+  
+    def validate_keys(hash)
+      # assume keys are already stringified
+      invalid_keys = hash.keys - self.class.valid_keys
+      unless invalid_keys.empty?
+        raise ArgumentError, "Invalid keys: #{invalid_keys.join(', ')}. Valid keys are: #{self.class.valid_keys.join(', ')}"
+      end
+    end
+  
+    def method_missing(name, *args)
+      name = name.to_s
+      if self.class.valid_keys.include?(name)
+        if args.empty?
+          @address_info[name]
+        else
+          @address_info[name] = standardize_value(args.first)
+        end
+      else
+        super(name.to_sym, *args)
+      end
+    end
+    
+    def ==(other)
+      other.kind_of?(AbstractAddress) && @address_info == other.address_info
+    end
+    
+  private
+    def standardize_values!(hash)
+      hash.each {|k,v| hash[k] = standardize_value(v) }
+    end
+    
+    def standardize_value(value)
+      value ? value.strip_whitespace : ""
+    end
+  end
+end

data/lib/address_standardization/class_level_inheritable_attributes.rb

@@ -0,0 +1,26 @@
+# from <http://railstips.org/2006/11/18/class-and-instance-variables-in-ruby>
+module ClassLevelInheritableAttributes
+  def self.included(base)
+    base.extend(ClassMethods)    
+  end
+
+  module ClassMethods
+    def inheritable_attributes(*args)
+      @inheritable_attributes ||= [:inheritable_attributes]
+      @inheritable_attributes += args
+      args.each do |arg|
+        class_eval %(
+          class << self; attr_accessor :#{arg} end
+        )
+      end
+      @inheritable_attributes
+    end
+
+    def inherited(subclass)
+      @inheritable_attributes.each do |inheritable_attribute|
+        instance_var = "@#{inheritable_attribute}" 
+        subclass.instance_variable_set(instance_var, instance_variable_get(instance_var))
+      end
+    end
+  end
+end

data/lib/address_standardization/google_maps.rb

@@ -0,0 +1,59 @@
+require 'rubygems'
+require 'hpricot'
+
+module AddressStandardization
+  module GoogleMaps
+    class << self
+      attr_accessor :api_key
+    end
+    
+    class Address < AbstractAddress
+      self.valid_keys = %w(street city state province postalcode zip country full_address precision)
+      
+      class << self
+        # much of this code was borrowed from GeoKit, thanks...
+        def standardize(address_info)
+          raise "API key not specified.\nCall AddressStandardization::GoogleMaps.api_key = '...' before you call .standardize()." unless GoogleMaps.api_key
+          
+          address_str = "%s, %s, %s %s" % [
+            address_info[:street],
+            address_info[:city],
+            (address_info[:state] || address_info[:province]),
+            address_info[:zip]
+          ]
+          url = "http://maps.google.com/maps/geo?q=#{address_str.url_escape}&output=xml&key=#{GoogleMaps.api_key}&oe=utf-8"
+          # puts url
+          uri = URI.parse(url)
+          res = Net::HTTP.get_response(uri)
+          unless res.is_a?(Net::HTTPSuccess)
+            File.open("test.xml", "w") {|f| f.write("(no response or response was unsuccessful)") }
+            return nil 
+          end
+          xml = res.body
+          #File.open("test.xml", "w") {|f| f.write(xml) }
+          xml = Hpricot::XML(xml)
+          
+          if xml.at("//kml/Response/Status/code").inner_text == "200"
+            addr = {}
+            
+            addr[:street] = get_inner_text(xml, '//ThoroughfareName')
+            addr[:city] = get_inner_text(xml, '//LocalityName')
+            addr[:province] = addr[:state] = get_inner_text(xml, '//AdministrativeAreaName')
+            addr[:zip] = addr[:postalcode] = get_inner_text(xml, '//PostalCodeNumber')
+            addr[:country] = get_inner_text(xml, '//CountryName')
+            
+            new(addr)
+          else
+            #File.open("test.xml", "w") {|f| f.write("(no response or response was unsuccessful)") }
+            nil
+          end
+        end
+        
+      private
+        def get_inner_text(xml, xpath)
+          lambda {|x| x && x.inner_text.upcase }.call(xml.at(xpath))
+        end
+      end
+    end # Address
+  end # GoogleMaps
+end # AddressStandardization

data/lib/address_standardization/melissa_data.rb

@@ -0,0 +1,68 @@
+require 'rubygems'
+require 'mechanize'
+
+module AddressStandardization
+  class MelissaData
+    class BaseAddress < AbstractAddress
+      inheritable_attributes :start_url
+      
+      def initialize(address_info)
+        raise NotImplementedError, "You must define start_url" unless self.class.start_url
+        super(address_info)
+      end
+      
+      class << self
+      protected
+        def standardize(address_info, action, attrs_to_fields)
+          is_canada = (action =~ /Canadian/)
+          addr = new(address_info)
+          fields = nil
+          WWW::Mechanize.new do |ua|
+            form_page = ua.get(start_url)
+            form = form_page.form_with(:action => action) do |form|
+              attrs_to_fields.each do |attr, field|
+                form[field] = addr.send(attr)
+              end
+            end
+            results_page = form.submit(form.buttons.first)
+
+            table = results_page.search("form")[2].next_sibling.next_sibling
+            status_th = table.search(is_canada ? "td" : "th")[0]
+            return unless status_th && status_th.inner_text =~ /Address Verified/
+            main_td = table.search("tr:eq(#{is_canada ? 1 : 2})/td:eq(1)")
+            strongs = main_td.search("strong")
+            street = strongs.first.inner_text
+            strongs[1].search("a:gt(0)").remove
+            city, state, zip = strongs[1].inner_html.strip_newlines.strip_html.split(/(?:&\w+;)+/)
+            fields = [ street.upcase, city.upcase, state.upcase, zip.upcase ]
+          end
+          fields
+        end
+      end
+    end
+    
+    class USAddress < BaseAddress
+      self.start_url = 'http://www.melissadata.com/lookups/AddressVerify.asp'
+      self.valid_keys = %w(street city state zip)
+      
+      def self.standardize(address_info)
+        if fields = super(address_info, "AddressVerify.asp", :street => 'Address', :city => 'city', :state => 'state', :zip => 'zip')
+          street, city, state, zip = fields
+          new(:street => street, :city => city, :state => state, :zip => zip)
+        end
+      end
+    end
+    
+    class CanadianAddress < BaseAddress
+      self.start_url = 'http://www.melissadata.com/lookups/CanadianAddressVerify.asp'
+      self.valid_keys = %w(street city province postalcode)
+      
+      def self.standardize(address_info)
+        if fields = super(address_info, "CanadianAddressVerify.asp", :street => 'Street', :city => 'city', :province => 'Province', :postalcode => 'Postcode')
+          street, city, province, postalcode = fields
+          new(:street => street, :city => city, :province => province, :postalcode => postalcode)
+        end
+      end
+    end
+  end
+end

data/lib/address_standardization/ruby_ext.rb

@@ -0,0 +1,17 @@
+class String
+  def strip_html
+    gsub(/<\/?([^>]+)>/, '')
+  end
+  def strip_newlines
+    gsub(/[\r\n]+/, '')
+  end
+  def strip_whitespace
+    strip_newlines.squeeze(" ").strip
+  end
+  
+  def url_escape
+    gsub(/([^ a-zA-Z0-9_.-]+)/n) do
+      '%' + $1.unpack('H2' * $1.size).join('%').upcase
+    end.tr(' ', '+')
+  end
+end

data/lib/address_standardization/version.rb

@@ -0,0 +1,13 @@
+module AddressStandardization
+  module Version
+    
+    MAJOR = 0
+    MINOR = 1
+    TINY  = 0
+    
+    def self.to_s # :nodoc:
+      [MAJOR, MINOR, TINY].join('.')
+    end
+    
+  end
+end

data/test/google_maps_test.rb

@@ -0,0 +1,48 @@
+require 'test_helper'
+
+class GoogleMapsTest < Test::Unit::TestCase
+  before do
+    AddressStandardization::GoogleMaps.api_key = "ABQIAAAALHg3jKnK9wN9K3_ArJA6TxSTZ2OgdK08l2h0_gdsozNQ-6zpaxQvIY84J7Mh1fAHQrYGI4W27qKZaw"
+  end
+  
+  test "A valid US address" do
+    addr = AddressStandardization::GoogleMaps::Address.standardize(
+      :street => "1600 Amphitheatre Parkway",
+      :city => "Mountain View",
+      :state => "CA"
+    )
+    addr.should == AddressStandardization::GoogleMaps::Address.new(
+      "street" => "1600 AMPHITHEATRE PKWY",
+      "city" => "MOUNTAIN VIEW",
+      "state" => "CA",
+      "province" => "CA",
+      "postalcode" => "94043",
+      "country" => "USA"
+    )
+  end
+  
+  test "A valid Canadian address" do
+    addr = AddressStandardization::GoogleMaps::Address.standardize(
+      :street => "1770 Stenson Boulevard",
+      :city => "Peterborough",
+      :province => "ON"
+    )
+    addr.should == AddressStandardization::GoogleMaps::Address.new(
+      "street" => "1770 STENSON BLVD",
+      "city" => "PETERBOROUGH",
+      "state" => "ON",
+      "province" => "ON",
+      "postalcode" => "K9K",
+      "country" => "CANADA"
+    )
+  end
+  
+  test "An invalid address" do    
+    addr = AddressStandardization::GoogleMaps::Address.standardize(
+      :street => "123 Imaginary Lane",
+      :city => "Some Town",
+      :state => "AK"
+    )
+    addr.should == nil
+  end
+end

data/test/melissa_data_test.rb

@@ -0,0 +1,49 @@
+require 'test_helper'
+
+class MelissaDataTest < Test::Unit::TestCase
+  test "Valid USA address" do
+    addr = AddressStandardization::MelissaData::USAddress.standardize(
+      :street => "1 Infinite Loop",
+      :city => "Cupertino",
+      :state => "CA"
+    )
+    addr.should == AddressStandardization::MelissaData::USAddress.new(
+      "street" => "1 INFINITE LOOP",
+      "city" => "CUPERTINO",
+      "state" => "CA",
+      "zip" => "95014-2083"
+    )
+  end
+  
+  test "Invalid USA address" do
+    addr = AddressStandardization::MelissaData::USAddress.standardize(
+      :street => "123 Imaginary Lane",
+      :city => "Some Town",
+      :state => "AK"
+    )
+    addr.should == nil
+  end
+  
+  test "Valid Canadian address" do
+    addr = AddressStandardization::MelissaData::CanadianAddress.standardize(
+      :street => "103 Metig St",
+      :city => "Sault Ste Marie",
+      :province => "ON"
+    )
+    addr.should == AddressStandardization::MelissaData::CanadianAddress.new(
+      "street" => "103 METIG ST RR 4",
+      "province" => "ON",
+      "city" => "SAULT STE MARIE",
+      "postalcode" => "P6A 5K9"
+    )
+  end
+  
+  test "Invalid Canadian address" do
+    addr = AddressStandardization::MelissaData::CanadianAddress.standardize(
+      :street => "123 Imaginary Lane",
+      :city => "Some Town",
+      :province => "BC"
+    )
+    addr.should == nil
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,12 @@
+# http://sneaq.net/textmate-wtf
+$LOAD_PATH.reject! { |e| e.include? 'TextMate' }
+
+dir = File.dirname(__FILE__)
+lib = dir + "/../lib"
+$LOAD_PATH.unshift(lib)
+
+require 'rubygems'
+require 'context'
+require 'matchy'
+
+require 'address_standardization'

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification 
+name: mcmire-address_standardization
+version: !ruby/object:Gem::Version 
+  version: 0.2.0
+platform: ruby
+authors: 
+- Elliot Winkler
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-01-05 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: mechanize
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: 
+email: elliot.winkler@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- README.rdoc
+- Rakefile
+- lib/address_standardization
+- lib/address_standardization/abstract_address.rb
+- lib/address_standardization/class_level_inheritable_attributes.rb
+- lib/address_standardization/google_maps.rb
+- lib/address_standardization/melissa_data.rb
+- lib/address_standardization/ruby_ext.rb
+- lib/address_standardization/version.rb
+- lib/address_standardization.rb
+- test/google_maps_test.rb
+- test/melissa_data_test.rb
+- test/test.xml
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/mcmire/address_standardization
+post_install_message: 
+rdoc_options: 
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: A tiny Ruby library to quickly standardize a postal address
+test_files: []
+