address_standardization 0.3.0

data/.gitignore

@@ -0,0 +1,3 @@
+.DS_Store
+*.gemspec
+*.gem

data/README.rdoc

@@ -0,0 +1,90 @@
+# address_standardization
+
+## Summary
+
+A tiny Ruby library to quickly standardize a postal address, either through MelissaData or Google Maps.
+
+## Installation
+
+If you are using Rails, put this in your environment.rb:
+
+    config.gem 'address_standardization'
+
+Then run `rake gems:install` to install the gem.
+
+Otherwise, just run
+
+    gem install address_standardization
+
+## Usage
+
+Right now this library supports two services: MelissaData and Google Maps.
+
+MelissaData provides two services itself: [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 `AddressStandardization::MelissaData::USAddress`. 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"
+
+Note that we refer to the province as `province`, but `state` works too. The postal code may also be referred to as `zip`.
+
+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"
+
+Sharp eyes will notice that 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).
+
+## Support
+
+If you find any bugs with this plugin, feel free to:
+
+* file a bug report in the [Issues area on Github](http://github.com/mcmire/address_standardization/issues)
+* fork the [project on Github](http://github.com/mcmire/address_standardization) and send me a pull request
+* email me (*firstname* dot *lastname* at gmail dot com)
+
+## Author/License
+
+(c) 2008 Elliot Winkler. Released under the MIT license.

data/Rakefile

@@ -0,0 +1,56 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "address_standardization"
+    gem.summary = %Q{A tiny Ruby library to quickly standardize a postal address}
+    gem.description = %Q{A tiny Ruby library to quickly standardize a postal address}
+    gem.authors = ["Elliot Winkler"]
+    gem.email = "elliot.winkler@gmail.com"
+    gem.homepage = "http://github.com/mcmire/address_standardization"
+    gem.add_dependency "mechanize"
+    gem.add_dependency "hpricot"
+    gem.add_development_dependency "mcmire-contest"
+    gem.add_development_dependency "mcmire-matchy"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "address_standardization #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/TODO

@@ -0,0 +1 @@
+* MelissaData will let us know if there are other residents in the building that the address points to and thus whether to supply the suite number -- tap into this

data/VERSION

@@ -0,0 +1 @@
+0.3.0

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
+    
+    extend ClassLevelInheritableAttributes
+    cattr_inheritable :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,20 @@
+# from <http://railstips.org/2008/6/13/a-class-instance-variable-update>
+module ClassLevelInheritableAttributes
+  def cattr_inheritable(*args)
+    @cattr_inheritable_attrs ||= [:cattr_inheritable_attrs]
+    @cattr_inheritable_attrs += args
+    args.each do |arg|
+      class_eval %(
+        class << self; attr_accessor :#{arg} end
+      )
+    end
+    @cattr_inheritable_attrs
+  end
+
+  def inherited(subclass)
+    @cattr_inheritable_attrs.each do |inheritable_attribute|
+      instance_var = "@#{inheritable_attribute}" 
+      subclass.instance_variable_set(instance_var, instance_variable_get(instance_var))
+    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,71 @@
+require 'rubygems'
+require 'mechanize'
+
+module AddressStandardization
+  class MelissaData
+    class BaseAddress < AbstractAddress
+      cattr_inheritable :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("table.Tableresultborder")[1]
+            return unless table
+            status_row = table.at("span.Titresultableok")
+            return unless status_row && status_row.inner_text =~ /Address Verified/
+            main_td = table.search("tr:eq(#{is_canada ? 2 : 3})/td:eq(2)")
+            street_part, city_state_zip_part = main_td.inner_html.split("<br>")[0..1]
+            street = street_part.strip_html.strip_whitespace
+            city, state, zip = city_state_zip_part.strip_html.split("\240\240")
+            #pp :main_td => main_td.to_s,
+            #   :street_part => street_part,
+            #   :city_state_zip_part => city_state_zip_part
+            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/test/google_maps_test.rb

@@ -0,0 +1,48 @@
+require 'test_helper'
+
+AddressStandardization::GoogleMaps.api_key = "ABQIAAAALHg3jKnK9wN9K3_ArJA6TxSTZ2OgdK08l2h0_gdsozNQ-6zpaxQvIY84J7Mh1fAHQrYGI4W27qKZaw"
+
+class GoogleMapsTest < Test::Unit::TestCase
+  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",
+      "zip" => "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",
+      "zip" => "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 US 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 US 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 => "3025 Clayhill Rd",
+      :city => "Mississauga",
+      :province => "ON"
+    )
+    addr.should == AddressStandardization::MelissaData::CanadianAddress.new(
+      "street" => "3025 CLAYHILL RD",
+      "province" => "ON",
+      "city" => "MISSISSAUGA",
+      "postalcode" => "L5B 4L2"
+    )
+  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,110 @@
+--- !ruby/object:Gem::Specification 
+name: address_standardization
+version: !ruby/object:Gem::Version 
+  version: 0.3.0
+platform: ruby
+authors: 
+- Elliot Winkler
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-01-01 00:00:00 -06:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: mechanize
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: hpricot
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: mcmire-contest
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: mcmire-matchy
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: A tiny Ruby library to quickly standardize a postal address
+email: elliot.winkler@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+- TODO
+files: 
+- .gitignore
+- README.rdoc
+- Rakefile
+- TODO
+- VERSION
+- lib/address_standardization.rb
+- 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
+- test/google_maps_test.rb
+- test/melissa_data_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/mcmire/address_standardization
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+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.3.5
+signing_key: 
+specification_version: 3
+summary: A tiny Ruby library to quickly standardize a postal address
+test_files: 
+- test/google_maps_test.rb
+- test/melissa_data_test.rb
+- test/test_helper.rb