Pr0d1r2-geokit 1.3.2

data/Manifest.txt

@@ -0,0 +1,29 @@
+.project
+History.txt
+Manifest.txt
+README.markdown
+Rakefile
+geokit.gemspec
+lib/geokit.rb
+lib/geokit/geocoders.rb
+lib/geokit/mappable.rb
+test/test_base_geocoder.rb
+test/test_bounds.rb
+test/test_ca_geocoder.rb
+test/test_geoloc.rb
+test/test_geoplugin_geocoder.rb
+test/test_google_geocoder.rb
+test/test_google_reverse_geocoder.rb
+test/test_inflector.rb
+test/test_ipgeocoder.rb
+test/test_latlng.rb
+test/test_multi_geocoder.rb
+test/test_us_geocoder.rb
+test/test_yahoo_geocoder.rb
+generators/geokit_cached/geokit_cached_generator.rb
+generators/geokit_cached/templates/model.rb
+generators/geokit_cached/templates/model_spec.rb
+lib/geokit/cached.rb
+lib/geokit/cached/geocodable.rb
+lib/geokit/cached/model.rb
+lib/geokit/geocoders/cached_multi_geocoder.rb

data/README.markdown

@@ -0,0 +1,264 @@
+## GEOKIT GEM DESCRIPTION
+
+The Geokit gem provides:
+
+ * Distance calculations between two points on the earth. Calculate the distance in miles, kilometers, or nautical miles, with all the trigonometry abstracted away by GeoKit.
+ * Geocoding from multiple providers. It supports Google, Yahoo, Geocoder.us, and Geocoder.ca geocoders, and others. It provides a uniform response structure from all of them. 
+   It also provides a fail-over mechanism, in case your input fails to geocode in one service.
+ * Rectangular bounds calculations: is a point within a given rectangular bounds?
+ * Heading and midpoint calculations
+
+Combine this gem with the [geokit-rails plugin](http://github.com/andre/geokit-rails/tree/master) to get location-based finders for your Rails app.
+
+* Geokit Documentation at Rubyforge [http://geokit.rubyforge.org](http://geokit.rubyforge.org).
+* Repository at Github: [http://github.com/andre/geokit-gem/tree/master](http://github.com/andre/geokit-gem/tree/master).
+* Follow the Google Group for updates and discussion on Geokit: [http://groups.google.com/group/geokit](http://groups.google.com/group/geokit) 
+
+## INSTALL
+
+    sudo gem install geokit
+
+## QUICK START
+
+		irb> require 'rubygems'
+		irb> require 'geokit'
+		irb> a=Geokit::Geocoders::YahooGeocoder.geocode '140 Market St, San Francisco, CA'
+		irb> a.ll
+		 => 37.79363,-122.396116
+		irb> b=Geokit::Geocoders::YahooGeocoder.geocode '789 Geary St, San Francisco, CA'
+		irb> b.ll
+		 => 37.786217,-122.41619
+		irb> a.distance_to(b)
+		 => 1.21120007413626
+		irb> a.heading_to(b)
+		=> 244.959832435678
+		irb(main):006:0> c=a.midpoint_to(b)      # what's halfway from a to b?
+		irb> c.ll
+		=> "37.7899239257175,-122.406153503469"
+		irb(main):008:0> d=c.endpoint(90,10)     # what's 10 miles to the east of c?
+		irb> d.ll
+		=> "37.7897825005142,-122.223214776155"
+
+FYI, that `.ll` method means "latitude longitude".
+
+See the RDOC more more ... there are also operations on rectangular bounds (e.g., determining if a point is within bounds, find the center, etc).
+
+## CONFIGURATION
+
+If you're using this gem by itself, here are the configuration options:
+
+		# These defaults are used in Geokit::Mappable.distance_to and in acts_as_mappable
+		Geokit::default_units = :miles
+		Geokit::default_formula = :sphere
+		
+		# This is the timeout value in seconds to be used for calls to the geocoder web
+		# services.  For no timeout at all, comment out the setting.  The timeout unit
+		# is in seconds. 
+		Geokit::Geocoders::timeout = 3
+		
+		# These settings are used if web service calls must be routed through a proxy.
+		# These setting can be nil if not needed, otherwise, addr and port must be 
+		# filled in at a minimum.  If the proxy requires authentication, the username
+		# and password can be provided as well.
+		Geokit::Geocoders::proxy_addr = nil
+		Geokit::Geocoders::proxy_port = nil
+		Geokit::Geocoders::proxy_user = nil
+		Geokit::Geocoders::proxy_pass = nil
+		
+		# This is your yahoo application key for the Yahoo Geocoder.
+		# See http://developer.yahoo.com/faq/index.html#appid
+		# and http://developer.yahoo.com/maps/rest/V1/geocode.html
+		Geokit::Geocoders::yahoo = 'REPLACE_WITH_YOUR_YAHOO_KEY'
+		    
+		# This is your Google Maps geocoder key. 
+		# See http://www.google.com/apis/maps/signup.html
+		# and http://www.google.com/apis/maps/documentation/#Geocoding_Examples
+		Geokit::Geocoders::google = 'REPLACE_WITH_YOUR_GOOGLE_KEY'
+		
+		# You can also set multiple API KEYS for different domains that may be directed to this same application.
+		# The domain from which the current user is being directed will automatically be updated for Geokit via
+		# the GeocoderControl class, which gets it's begin filter mixed into the ActionController.
+		# You define these keys with a Hash as follows:
+		#Geokit::Geocoders::google = { 'rubyonrails.org' => 'RUBY_ON_RAILS_API_KEY', 'ruby-docs.org' => 'RUBY_DOCS_API_KEY' }
+		    
+		# This is your username and password for geocoder.us.
+		# To use the free service, the value can be set to nil or false.  For 
+		# usage tied to an account, the value should be set to username:password.
+		# See http://geocoder.us
+		# and http://geocoder.us/user/signup
+		Geokit::Geocoders::geocoder_us = false 
+		
+		# This is your authorization key for geocoder.ca.
+		# To use the free service, the value can be set to nil or false.  For 
+		# usage tied to an account, set the value to the key obtained from
+		# Geocoder.ca.
+		# See http://geocoder.ca
+		# and http://geocoder.ca/?register=1
+		Geokit::Geocoders::geocoder_ca = false
+		
+		# require "external_geocoder.rb"
+		# Please see the section "writing your own geocoders" for more information.
+		# Geokit::Geocoders::external_key = 'REPLACE_WITH_YOUR_API_KEY'
+		
+		# This is the order in which the geocoders are called in a failover scenario
+		# If you only want to use a single geocoder, put a single symbol in the array.
+		# Valid symbols are :google, :yahoo, :us, and :ca.
+		# Be aware that there are Terms of Use restrictions on how you can use the 
+		# various geocoders.  Make sure you read up on relevant Terms of Use for each
+		# geocoder you are going to use.
+		Geokit::Geocoders::provider_order = [:google,:us]
+		
+		# The IP provider order. Valid symbols are :ip,:geo_plugin.
+		# As before, make sure you read up on relevant Terms of Use for each.
+		# Geokit::Geocoders::ip_provider_order = [:external,:geo_plugin,:ip]
+
+If you're using this gem with the [geokit-rails plugin](http://github.com/andre/geokit-rails/tree/master), the plugin
+creates a template with these settings and places it in `config/initializers/geokit_config.rb`.
+
+## SUPPORTED GEOCODERS
+
+### "regular" address geocoders 
+* Yahoo Geocoder - requires an API key.
+* Geocoder.us - may require authentication if performing more than the free request limit.
+* Geocoder.ca - for Canada; may require authentication as well.
+* Geonames - a free geocoder
+
+### address geocoders that also provide reverse geocoding 
+* Google Geocoder - requires an API key. Also supports multiple results.
+
+### IP address geocoders 
+* IP Geocoder - geocodes an IP address using hostip.info's web service.
+* Geoplugin.net -- another IP address geocoder
+
+### The Multigeocoder
+Multi Geocoder - provides failover for the physical location geocoders, and also IP address geocoders. Its configured by setting Geokit::Geocoders::provider_order, and Geokit::Geocoders::ip_provider_order. You should call the Multi-Geocoder with its :geocode method, supplying one address parameter which is either a real street address, or an ip address. For example:
+
+		Geokit::Geocoders::MultiGeocoder.geocode("900 Sycamore Drive")
+
+		Geokit::Geocoders::MultiGeocoder.geocode("12.12.12.12")
+
+## MULTIPLE RESULTS
+Some geocoding services will return multple results if the there isn't one clear result. 
+Geoloc can capture multiple results through its "all" method. Currently only the Google geocoder 
+supports multiple results:
+
+		irb> geo=Geokit::Geocoders::GoogleGeocoder.geocode("900 Sycamore Drive")
+		irb> geo.full_address
+		=> "900 Sycamore Dr, Arkadelphia, AR 71923, USA"
+		irb> geo.all.size
+		irb> geo.all.each { |e| puts e.full_address }
+		900 Sycamore Dr, Arkadelphia, AR 71923, USA
+		900 Sycamore Dr, Burkburnett, TX 76354, USA
+		900 Sycamore Dr, TN 38361, USA
+		.... 
+
+geo.all is just an array of additional Geolocs, so do what you want with it. If you call .all on a 
+geoloc that doesn't have any additional results, you will get  an array of one.
+
+
+## NOTES ON WHAT'S WHERE
+
+mappable.rb contains the Mappable module, which provides basic
+distance calculation methods, i.e., calculating the distance
+between two points. 
+
+mappable.rb also contains LatLng, GeoLoc, and Bounds.
+LatLng is a simple container for latitude and longitude, but 
+it's made more powerful by mixing in the above-mentioned Mappable
+module -- therefore, you can calculate easily the distance between two
+LatLng ojbects with `distance = first.distance_to(other)`
+
+GeoLoc (also in mappable.rb) represents an address or location which
+has been geocoded. You can get the city, zipcode, street address, etc.
+from a GeoLoc object. GeoLoc extends LatLng, so you also get lat/lng
+AND the Mappable modeule goodness for free.
+
+geocoders.rb contains all the geocoder implemenations. All the gercoders 
+inherit from a common base (class Geocoder) and implement the private method
+do_geocode.
+
+## WRITING YOUR OWN GEOCODERS
+
+If you would like to write your own geocoders, you can do so by requiring 'geokit' or 'geokit/geocoders.rb' in a new file and subclassing the base class (which is class "Geocoder").
+You must then also require such extenal file back in your main geokit configuration.
+
+	require "geokit"
+
+	module Geokit
+	  module Geocoders
+   		
+		# Should be overriden as Geokit::Geocoders::external_key in your configuration file
+	    @@external_key = 'REPLACE_WITH_YOUR_API_KEY'
+	    __define_accessors
+   
+		# Replace name 'External' (below) with the name of your custom geocoder class
+		# and use :external to specify this geocoder in your list of geocoders.
+	    class ExternalGeocoder < Geocoder
+	      private 
+	      def self.do_geocode(address)
+	        # Main geocoding method
+	      end
+
+	      def self.parse_http_resp(body) # :nodoc:
+	        # Helper method to parse http response. See geokit/geocoders.rb.
+	      end
+	    end
+	
+	  end
+	end
+
+
+## CACHING SUPPORT
+
+From now on we have an caching support for MultiGeocoder.
+It is designed for ActiveRecord.
+It prefers google over other geocoders (best support for Europe).
+It requires rspec and rspec-rails to operate.
+
+First You need to generate some code:
+
+./script/generate geokit_cached
+
+One change to active record model storing the cache (generate does not generate this):
+
+class CachedLocation < ActiveRecord::Base
+  include Geokit::Cached::Model
+end
+
+You can enable it in Your models:
+
+class Profile < ActiveRecord::Base
+  include Geokit::Cached::Geocodable
+  CACHE_LOCATIONS = true
+  before_save :geocode_address_cached
+end
+
+
+## GOOGLE GROUP
+
+Follow the Google Group for updates and discussion on Geokit: http://groups.google.com/group/geokit 
+
+## LICENSE
+
+(The MIT License)
+
+Copyright (c) 2007-2009 Andre Lewis and Bill Eisenhauer
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,22 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+require './lib/geokit.rb'
+
+# undefined method `empty?' for nil:NilClass
+# /Library/Ruby/Site/1.8/rubygems/specification.rb:886:in `validate' 
+class NilClass
+  def empty?
+    true
+  end
+end 
+
+project=Hoe.new('geokit', Geokit::VERSION) do |p|
+  #p.rubyforge_name = 'geokit' # if different than lowercase project name
+  p.developer('Andre Lewis', 'andre@earthcode.com')
+  p.summary="Geokit provides geocoding and distance calculation in an easy-to-use API"
+end
+
+
+# vim: syntax=Ruby

data/lib/geokit.rb

@@ -0,0 +1,31 @@
+module Geokit
+  VERSION = '1.3.2'
+  # These defaults are used in Geokit::Mappable.distance_to and in acts_as_mappable
+  @@default_units = :miles
+  @@default_formula = :sphere
+
+  [:default_units, :default_formula].each do |sym|
+    class_eval <<-EOS, __FILE__, __LINE__
+      def self.#{sym}
+        if defined?(#{sym.to_s.upcase})
+          #{sym.to_s.upcase}
+        else
+          @@#{sym}
+        end
+      end
+
+      def self.#{sym}=(obj)
+        @@#{sym} = obj
+      end
+    EOS
+  end
+end
+
+path = File.expand_path(File.dirname(__FILE__))
+$: <<  path unless $:.include?(path)
+require 'geokit/geocoders'
+require 'geokit/mappable'
+require 'geokit/cached'
+
+# make old-style module name "GeoKit" equivalent to new-style "Geokit"
+GeoKit=Geokit

data/lib/geokit/geocoders.rb

@@ -0,0 +1,586 @@
+require 'net/http'
+require 'rexml/document'
+require 'yaml'
+require 'timeout'
+require 'logger'
+
+require 'geocoders/cached_multi_geocoder'
+
+module Geokit
+  module Inflector
+   
+    extend self
+   
+    def titleize(word)
+      humanize(underscore(word)).gsub(/\b([a-z])/u) { $1.capitalize }
+    end
+   
+    def underscore(camel_cased_word)
+      camel_cased_word.to_s.gsub(/::/, '/').
+      gsub(/([A-Z]+)([A-Z][a-z])/u,'\1_\2').
+      gsub(/([a-z\d])([A-Z])/u,'\1_\2').
+      tr("-", "_").
+      downcase
+    end
+   
+    def humanize(lower_case_and_underscored_word)
+      lower_case_and_underscored_word.to_s.gsub(/_id$/, "").gsub(/_/, " ").capitalize
+    end
+    
+    def snake_case(s)
+      return s.downcase if s =~ /^[A-Z]+$/u
+      s.gsub(/([A-Z]+)(?=[A-Z][a-z]?)|\B[A-Z]/u, '_\&') =~ /_*(.*)/
+        return $+.downcase
+      
+    end
+    
+    def url_escape(s)
+    s.gsub(/([^ a-zA-Z0-9_.-]+)/nu) do
+      '%' + $1.unpack('H2' * $1.size).join('%').upcase
+      end.tr(' ', '+')
+    end
+    
+    def camelize(str)
+      str.split('_').map {|w| w.capitalize}.join
+    end
+  end  
+  
+  # Contains a range of geocoders:
+  # 
+  # ### "regular" address geocoders 
+  # * Yahoo Geocoder - requires an API key.
+  # * Geocoder.us - may require authentication if performing more than the free request limit.
+  # * Geocoder.ca - for Canada; may require authentication as well.
+  # * Geonames - a free geocoder
+  #
+  # ### address geocoders that also provide reverse geocoding 
+  # * Google Geocoder - requires an API key.
+  #  
+  # ### IP address geocoders 
+  # * IP Geocoder - geocodes an IP address using hostip.info's web service.
+  # * Geoplugin.net -- another IP address geocoder
+  #
+  # ### The Multigeocoder
+  # * Multi Geocoder - provides failover for the physical location geocoders.
+  # 
+  # Some of these geocoders require configuration. You don't have to provide it here. See the README.
+  module Geocoders
+    @@proxy_addr = nil
+    @@proxy_port = nil
+    @@proxy_user = nil
+    @@proxy_pass = nil
+    @@timeout = nil    
+    @@yahoo = 'REPLACE_WITH_YOUR_YAHOO_KEY'
+    @@google = 'REPLACE_WITH_YOUR_GOOGLE_KEY'
+    @@geocoder_us = false
+    @@geocoder_ca = false
+    @@geonames = false
+    @@provider_order = [:google,:us]
+    @@ip_provider_order = [:geo_plugin,:ip]
+    @@logger=Logger.new(STDOUT)
+    @@logger.level=Logger::INFO
+    @@domain = nil
+    
+    def self.__define_accessors
+      class_variables.each do |v| 
+        sym = v.delete("@").to_sym
+        unless self.respond_to? sym
+          module_eval <<-EOS, __FILE__, __LINE__
+            def self.#{sym}
+              value = if defined?(#{sym.to_s.upcase})
+                #{sym.to_s.upcase}
+              else
+                @@#{sym}
+              end
+              if value.is_a?(Hash)
+                value = (self.domain.nil? ? nil : value[self.domain]) || value.values.first
+              end
+              value
+            end
+          
+            def self.#{sym}=(obj)
+              @@#{sym} = obj
+            end
+          EOS
+        end
+      end
+    end
+
+    __define_accessors
+    
+    # Error which is thrown in the event a geocoding error occurs.
+    class GeocodeError < StandardError; end
+
+    # -------------------------------------------------------------------------------------------
+    # Geocoder Base class -- every geocoder should inherit from this
+    # -------------------------------------------------------------------------------------------    
+    
+    # The Geocoder base class which defines the interface to be used by all
+    # other geocoders.
+    class Geocoder   
+      # Main method which calls the do_geocode template method which subclasses
+      # are responsible for implementing.  Returns a populated GeoLoc or an
+      # empty one with a failed success code.
+      def self.geocode(address)  
+        res = do_geocode(address)
+        return res.nil? ? GeoLoc.new : res
+      end  
+      # Main method which calls the do_reverse_geocode template method which subclasses
+      # are responsible for implementing.  Returns a populated GeoLoc or an
+      # empty one with a failed success code.
+      def self.reverse_geocode(latlng)
+        res = do_reverse_geocode(latlng)
+        return res.success? ? res : GeoLoc.new        
+      end
+      
+      # Call the geocoder service using the timeout if configured.
+      def self.call_geocoder_service(url)
+        timeout(Geokit::Geocoders::timeout) { return self.do_get(url) } if Geokit::Geocoders::timeout        
+        return self.do_get(url)
+      rescue TimeoutError
+        return nil  
+      end
+
+      # Not all geocoders can do reverse geocoding. So, unless the subclass explicitly overrides this method,
+      # a call to reverse_geocode will return an empty GeoLoc. If you happen to be using MultiGeocoder,
+      # this will cause it to failover to the next geocoder, which will hopefully be one which supports reverse geocoding.
+      def self.do_reverse_geocode(latlng)
+        return GeoLoc.new
+      end
+
+      protected
+
+      def self.logger() 
+        Geokit::Geocoders::logger
+      end
+      
+      private
+      
+      # Wraps the geocoder call around a proxy if necessary.
+      def self.do_get(url) 
+        uri = URI.parse(url)
+        req = Net::HTTP::Get.new(url)
+        req.basic_auth(uri.user, uri.password) if uri.userinfo
+        res = Net::HTTP::Proxy(GeoKit::Geocoders::proxy_addr,
+                GeoKit::Geocoders::proxy_port,
+                GeoKit::Geocoders::proxy_user,
+                GeoKit::Geocoders::proxy_pass).start(uri.host, uri.port) { |http| http.request(req) }
+
+        return res
+      end
+      
+      # Adds subclass' geocode method making it conveniently available through 
+      # the base class.
+      def self.inherited(clazz)
+        class_name = clazz.name.split('::').last
+        src = <<-END_SRC
+          def self.#{Geokit::Inflector.underscore(class_name)}(address)
+            #{class_name}.geocode(address)
+          end
+        END_SRC
+        class_eval(src)
+      end
+    end
+
+    # -------------------------------------------------------------------------------------------
+    # "Regular" Address geocoders
+    # -------------------------------------------------------------------------------------------    
+    
+    # Geocoder CA geocoder implementation.  Requires the Geokit::Geocoders::GEOCODER_CA variable to
+    # contain true or false based upon whether authentication is to occur.  Conforms to the 
+    # interface set by the Geocoder class.
+    #
+    # Returns a response like:
+    # <?xml version="1.0" encoding="UTF-8" ?>
+    # <geodata>
+    #   <latt>49.243086</latt>
+    #   <longt>-123.153684</longt>
+    # </geodata>
+    class CaGeocoder < Geocoder
+
+      private
+
+      # Template method which does the geocode lookup.
+      def self.do_geocode(address)
+        raise ArgumentError('Geocoder.ca requires a GeoLoc argument') unless address.is_a?(GeoLoc)
+        url = construct_request(address)
+        res = self.call_geocoder_service(url)
+        return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
+        xml = res.body
+        logger.debug "Geocoder.ca geocoding. Address: #{address}. Result: #{xml}"
+        # Parse the document.
+        doc = REXML::Document.new(xml)    
+        address.lat = doc.elements['//latt'].text
+        address.lng = doc.elements['//longt'].text
+        address.success = true
+        return address
+      rescue
+        logger.error "Caught an error during Geocoder.ca geocoding call: "+$!
+        return GeoLoc.new  
+      end  
+
+      # Formats the request in the format acceptable by the CA geocoder.
+      def self.construct_request(location)
+        url = ""
+        url += add_ampersand(url) + "stno=#{location.street_number}" if location.street_address
+        url += add_ampersand(url) + "addresst=#{Geokit::Inflector::url_escape(location.street_name)}" if location.street_address
+        url += add_ampersand(url) + "city=#{Geokit::Inflector::url_escape(location.city)}" if location.city
+        url += add_ampersand(url) + "prov=#{location.state}" if location.state
+        url += add_ampersand(url) + "postal=#{location.zip}" if location.zip
+        url += add_ampersand(url) + "auth=#{Geokit::Geocoders::geocoder_ca}" if Geokit::Geocoders::geocoder_ca
+        url += add_ampersand(url) + "geoit=xml"
+        'http://geocoder.ca/?' + url
+      end
+
+      def self.add_ampersand(url)
+        url && url.length > 0 ? "&" : ""
+      end
+    end    
+    
+    # Geocoder Us geocoder implementation.  Requires the Geokit::Geocoders::GEOCODER_US variable to
+    # contain true or false based upon whether authentication is to occur.  Conforms to the 
+    # interface set by the Geocoder class.
+    class UsGeocoder < Geocoder
+
+      private
+      def self.do_geocode(address)
+        address_str = address.is_a?(GeoLoc) ? address.to_geocodeable_s : address
+        
+        query = (address_str =~ /^\d{5}(?:-\d{4})?$/ ? "zip" : "address") + "=#{Geokit::Inflector::url_escape(address_str)}"
+        url = if GeoKit::Geocoders::geocoder_us         
+          "http://#{GeoKit::Geocoders::geocoder_us}@geocoder.us/member/service/csv/geocode"
+        else
+          "http://geocoder.us/service/csv/geocode"
+        end
+        
+        url = "#{url}?#{query}"  
+        res = self.call_geocoder_service(url)
+        
+        return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
+        data = res.body
+        logger.debug "Geocoder.us geocoding. Address: #{address}. Result: #{data}"
+        array = data.chomp.split(',')
+        
+        if array.length == 5
+          res=GeoLoc.new
+          res.lat,res.lng,res.city,res.state,res.zip=array
+          res.country_code='US'
+          res.success=true
+          return res
+        elsif array.length == 6  
+          res=GeoLoc.new 
+          res.lat,res.lng,res.street_address,res.city,res.state,res.zip=array
+          res.country_code='US'
+          res.success=true 
+          return res
+        else 
+          logger.info "geocoder.us was unable to geocode address: "+address
+          return GeoLoc.new      
+        end
+        rescue 
+          logger.error "Caught an error during geocoder.us geocoding call: "+$!
+          return GeoLoc.new
+
+      end
+    end
+    
+    # Yahoo geocoder implementation.  Requires the Geokit::Geocoders::YAHOO variable to
+    # contain a Yahoo API key.  Conforms to the interface set by the Geocoder class.
+    class YahooGeocoder < Geocoder
+
+      private 
+
+      # Template method which does the geocode lookup.
+      def self.do_geocode(address)
+        address_str = address.is_a?(GeoLoc) ? address.to_geocodeable_s : address
+        url="http://api.local.yahoo.com/MapsService/V1/geocode?appid=#{Geokit::Geocoders::yahoo}&location=#{Geokit::Inflector::url_escape(address_str)}"
+        res = self.call_geocoder_service(url)
+        return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
+        xml = res.body
+        doc = REXML::Document.new(xml)
+        logger.debug "Yahoo geocoding. Address: #{address}. Result: #{xml}"
+
+        if doc.elements['//ResultSet']
+          res=GeoLoc.new
+
+          #basic      
+          res.lat=doc.elements['//Latitude'].text
+          res.lng=doc.elements['//Longitude'].text
+          res.country_code=doc.elements['//Country'].text
+          res.provider='yahoo'  
+
+          #extended - false if not available
+          res.city=doc.elements['//City'].text if doc.elements['//City'] && doc.elements['//City'].text != nil
+          res.state=doc.elements['//State'].text if doc.elements['//State'] && doc.elements['//State'].text != nil
+          res.zip=doc.elements['//Zip'].text if doc.elements['//Zip'] && doc.elements['//Zip'].text != nil
+          res.street_address=doc.elements['//Address'].text if doc.elements['//Address'] && doc.elements['//Address'].text != nil
+          res.precision=doc.elements['//Result'].attributes['precision'] if doc.elements['//Result']
+          # set the accuracy as google does (added by Andruby)
+          res.accuracy=%w{unknown country state state city zip zip+4 street address building}.index(res.precision)
+          res.success=true
+          return res
+        else 
+          logger.info "Yahoo was unable to geocode address: "+address
+          return GeoLoc.new
+        end   
+
+        rescue 
+          logger.info "Caught an error during Yahoo geocoding call: "+$!
+          return GeoLoc.new
+      end
+    end
+
+    # Another geocoding web service
+    # http://www.geonames.org
+    class GeonamesGeocoder < Geocoder
+
+      private 
+      
+      # Template method which does the geocode lookup.
+      def self.do_geocode(address)
+        address_str = address.is_a?(GeoLoc) ? address.to_geocodeable_s : address
+        # geonames need a space seperated search string
+        address_str.gsub!(/,/, " ")
+        params = "/postalCodeSearch?placename=#{Geokit::Inflector::url_escape(address_str)}&maxRows=10"
+        
+        if(GeoKit::Geocoders::geonames)
+          url = "http://ws.geonames.net#{params}&username=#{GeoKit::Geocoders::geonames}"
+        else
+          url = "http://ws.geonames.org#{params}"
+        end
+        
+        res = self.call_geocoder_service(url)
+        
+        return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
+        
+        xml=res.body
+        logger.debug "Geonames geocoding. Address: #{address}. Result: #{xml}"
+        doc=REXML::Document.new(xml)
+        
+        if(doc.elements['//geonames/totalResultsCount'].text.to_i > 0)
+          res=GeoLoc.new
+        
+          # only take the first result
+          res.lat=doc.elements['//code/lat'].text if doc.elements['//code/lat']
+          res.lng=doc.elements['//code/lng'].text if doc.elements['//code/lng']
+          res.country_code=doc.elements['//code/countryCode'].text if doc.elements['//code/countryCode']
+          res.provider='genomes'  
+          res.city=doc.elements['//code/name'].text if doc.elements['//code/name']
+          res.state=doc.elements['//code/adminName1'].text if doc.elements['//code/adminName1']
+          res.zip=doc.elements['//code/postalcode'].text if doc.elements['//code/postalcode']
+          res.success=true
+          return res
+        else 
+          logger.info "Geonames was unable to geocode address: "+address
+          return GeoLoc.new
+        end
+        
+        rescue
+          logger.error "Caught an error during Geonames geocoding call: "+$!
+      end
+    end
+
+    # -------------------------------------------------------------------------------------------
+    # Address geocoders that also provide reverse geocoding
+    # -------------------------------------------------------------------------------------------
+
+    # Google geocoder implementation.  Requires the Geokit::Geocoders::GOOGLE variable to
+    # contain a Google API key.  Conforms to the interface set by the Geocoder class.
+    class GoogleGeocoder < Geocoder
+
+      private 
+      
+      # Template method which does the reverse-geocode lookup.
+      def self.do_reverse_geocode(latlng) 
+        latlng=LatLng.normalize(latlng)
+        res = self.call_geocoder_service("http://maps.google.com/maps/geo?ll=#{Geokit::Inflector::url_escape(latlng.ll)}&output=xml&key=#{Geokit::Geocoders::google}&oe=utf-8")
+        #        res = Net::HTTP.get_response(URI.parse("http://maps.google.com/maps/geo?ll=#{Geokit::Inflector::url_escape(address_str)}&output=xml&key=#{Geokit::Geocoders::google}&oe=utf-8"))
+        return GeoLoc.new unless (res.is_a?(Net::HTTPSuccess) || res.is_a?(Net::HTTPOK))
+        xml = res.body
+        logger.debug "Google reverse-geocoding. LL: #{latlng}. Result: #{xml}"
+        return self.xml2GeoLoc(xml)        
+      end  
+
+      # Template method which does the geocode lookup.
+      def self.do_geocode(address)
+        address_str = address.is_a?(GeoLoc) ? address.to_geocodeable_s : address
+        res = self.call_geocoder_service("http://maps.google.com/maps/geo?q=#{Geokit::Inflector::url_escape(address_str)}&output=xml&key=#{Geokit::Geocoders::google}&oe=utf-8")
+        return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
+        xml = res.body
+        logger.debug "Google geocoding. Address: #{address}. Result: #{xml}"
+        return self.xml2GeoLoc(xml, address)        
+      end
+      
+      def self.xml2GeoLoc(xml, address="")
+        doc=REXML::Document.new(xml)
+
+        if doc.elements['//kml/Response/Status/code'].text == '200'
+          geoloc = nil
+          # Google can return multiple results as //Placemark elements. 
+          # iterate through each and extract each placemark as a geoloc
+          doc.each_element('//Placemark') do |e|
+            extracted_geoloc = extract_placemark(e) # g is now an instance of GeoLoc
+            if geoloc.nil? 
+              # first time through, geoloc is still nil, so we make it the geoloc we just extracted
+              geoloc = extracted_geoloc 
+            else
+              # second (and subsequent) iterations, we push additional 
+              # geolocs onto "geoloc.all" 
+              geoloc.all.push(extracted_geoloc) 
+            end  
+          end
+          return geoloc
+        else 
+          logger.info "Google was unable to geocode address: "+address
+          return GeoLoc.new
+        end
+
+        rescue
+          logger.error "Caught an error during Google geocoding call: "+$!
+          return GeoLoc.new
+      end  
+
+      # extracts a single geoloc from a //placemark element in the google results xml
+      def self.extract_placemark(doc)
+        res = GeoLoc.new
+        coordinates=doc.elements['.//coordinates'].text.to_s.split(',')
+
+        #basics
+        res.lat=coordinates[1]
+        res.lng=coordinates[0]
+        res.country_code=doc.elements['.//CountryNameCode'].text if doc.elements['.//CountryNameCode']
+        res.provider='google'
+
+        #extended -- false if not not available
+        res.city = doc.elements['.//LocalityName'].text if doc.elements['.//LocalityName']
+        res.state = doc.elements['.//AdministrativeAreaName'].text if doc.elements['.//AdministrativeAreaName']
+        res.full_address = doc.elements['.//address'].text if doc.elements['.//address'] # google provides it
+        res.zip = doc.elements['.//PostalCodeNumber'].text if doc.elements['.//PostalCodeNumber']
+        res.street_address = doc.elements['.//ThoroughfareName'].text if doc.elements['.//ThoroughfareName']
+        # Translate accuracy into Yahoo-style token address, street, zip, zip+4, city, state, country
+        # For Google, 1=low accuracy, 8=high accuracy
+        address_details=doc.elements['.//*[local-name() = "AddressDetails"]']
+        res.accuracy = address_details ? address_details.attributes['Accuracy'].to_i : 0
+        res.precision=%w{unknown country state state city zip zip+4 street address building}[res.accuracy]
+        res.success=true
+        
+        return res        
+      end
+    end
+
+
+    # -------------------------------------------------------------------------------------------
+    # IP Geocoders
+    # -------------------------------------------------------------------------------------------
+  
+    # Provides geocoding based upon an IP address.  The underlying web service is geoplugin.net
+    class GeoPluginGeocoder < Geocoder
+      private
+      
+      def self.do_geocode(ip)
+        return GeoLoc.new unless /^(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})?$/.match(ip)
+        response = self.call_geocoder_service("http://www.geoplugin.net/xml.gp?ip=#{ip}")
+        return response.is_a?(Net::HTTPSuccess) ? parse_xml(response.body) : GeoLoc.new
+      rescue
+        logger.error "Caught an error during GeoPluginGeocoder geocoding call: "+$!
+        return GeoLoc.new
+      end
+
+      def self.parse_xml(xml)
+        xml = REXML::Document.new(xml)
+        geo = GeoLoc.new
+        geo.provider='geoPlugin'
+        geo.city = xml.elements['//geoplugin_city'].text
+        geo.state = xml.elements['//geoplugin_region'].text
+        geo.country_code = xml.elements['//geoplugin_countryCode'].text
+        geo.lat = xml.elements['//geoplugin_latitude'].text.to_f
+        geo.lng = xml.elements['//geoplugin_longitude'].text.to_f
+        geo.success = !!geo.city && !geo.city.empty?
+        return geo
+      end
+    end
+
+    # Provides geocoding based upon an IP address.  The underlying web service is a hostip.info
+    # which sources their data through a combination of publicly available information as well
+    # as community contributions.
+    class IpGeocoder < Geocoder 
+
+      private 
+
+      # Given an IP address, returns a GeoLoc instance which contains latitude,
+      # longitude, city, and country code.  Sets the success attribute to false if the ip 
+      # parameter does not match an ip address.  
+      def self.do_geocode(ip)
+        return GeoLoc.new if '0.0.0.0' == ip
+        return GeoLoc.new unless /^(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})?$/.match(ip)
+        url = "http://api.hostip.info/get_html.php?ip=#{ip}&position=true"
+        response = self.call_geocoder_service(url)
+        response.is_a?(Net::HTTPSuccess) ? parse_body(response.body) : GeoLoc.new
+      rescue
+        logger.error "Caught an error during HostIp geocoding call: "+$!
+        return GeoLoc.new
+      end
+
+      # Converts the body to YAML since its in the form of:
+      #
+      # Country: UNITED STATES (US)
+      # City: Sugar Grove, IL
+      # Latitude: 41.7696
+      # Longitude: -88.4588
+      #
+      # then instantiates a GeoLoc instance to populate with location data.
+      def self.parse_body(body) # :nodoc:
+        yaml = YAML.load(body)
+        res = GeoLoc.new
+        res.provider = 'hostip'
+        res.city, res.state = yaml['City'].split(', ')
+        country, res.country_code = yaml['Country'].split(' (')
+        res.lat = yaml['Latitude'] 
+        res.lng = yaml['Longitude']
+        res.country_code.chop!
+        res.success = !(res.city =~ /\(.+\)/)
+        res
+      end
+    end
+    
+    # -------------------------------------------------------------------------------------------
+    # The Multi Geocoder
+    # -------------------------------------------------------------------------------------------    
+    
+    # Provides methods to geocode with a variety of geocoding service providers, plus failover
+    # among providers in the order you configure. When 2nd parameter is set 'true', perform
+    # ip location lookup with 'address' as the ip address.
+    # 
+    # Goal:
+    # - homogenize the results of multiple geocoders
+    # 
+    # Limitations:
+    # - currently only provides the first result. Sometimes geocoders will return multiple results.
+    # - currently discards the "accuracy" component of the geocoding calls
+    class MultiGeocoder < Geocoder       
+
+      private
+      # This method will call one or more geocoders in the order specified in the 
+      # configuration until one of the geocoders work.
+      # 
+      # The failover approach is crucial for production-grade apps, but is rarely used.
+      # 98% of your geocoding calls will be successful with the first call  
+      def self.do_geocode(address)
+        geocode_ip = /^(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.match(address)
+        provider_order = geocode_ip ? Geokit::Geocoders::ip_provider_order : Geokit::Geocoders::provider_order
+        
+        provider_order.each do |provider|
+          begin
+            klass = Geokit::Geocoders.const_get "#{Geokit::Inflector::camelize(provider.to_s)}Geocoder"
+            res = klass.send :geocode, address
+            return res if res.success?
+          rescue
+            logger.error("Something has gone very wrong during geocoding, OR you have configured an invalid class name in Geokit::Geocoders::provider_order. Address: #{address}. Provider: #{provider}")
+          end
+        end
+        # If we get here, we failed completely.
+        GeoLoc.new
+      end
+    end   
+  end
+end