andre-geokit 1.2.6 → 1.3.1

data/README.markdown

@@ -74,6 +74,12 @@ If you're using this gem by itself, here are the configuration options:
 		# 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 
@@ -90,6 +96,10 @@ If you're using this gem by itself, here are the configuration options:
 		# 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.
@@ -97,6 +107,10 @@ If you're using this gem by itself, here are the configuration options:
 		# 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`.
@@ -117,7 +131,11 @@ creates a template with these settings and places it in `config/initializers/geo
 * Geoplugin.net -- another IP address geocoder
 
 ### The Multigeocoder
-* Multi Geocoder - provides failover for the physical location geocoders.
+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. 
@@ -159,6 +177,36 @@ 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
+
 ## GOOGLE GROUP
 
 Follow the Google Group for updates and discussion on Geokit: http://groups.google.com/group/geokit 

data/lib/geokit.rb

@@ -1,5 +1,5 @@
 module Geokit
-  VERSION = '1.2.6'
+  VERSION = '1.3.1'
   # These defaults are used in Geokit::Mappable.distance_to and in acts_as_mappable
   @@default_units = :miles
   @@default_formula = :sphere

data/lib/geokit/geocoders.rb

@@ -37,6 +37,10 @@ module Geokit
       '%' + $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:
@@ -70,25 +74,37 @@ module Geokit
     @@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
     
-    [:yahoo, :google, :geocoder_us, :geocoder_ca, :geonames, :provider_order, :timeout, 
-     :proxy_addr, :proxy_port, :proxy_user, :proxy_pass,:logger].each do |sym|
-      class_eval <<-EOS, __FILE__, __LINE__
-        def self.#{sym}
-          if defined?(#{sym.to_s.upcase})
-            #{sym.to_s.upcase}
-          else
-            @@#{sym}
-          end
+    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
-
-        def self.#{sym}=(obj)
-          @@#{sym} = obj
-        end
-      EOS
+      end
     end
+
+    __define_accessors
     
     # Error which is thrown in the event a geocoding error occurs.
     class GeocodeError < StandardError; end
@@ -105,9 +121,8 @@ module Geokit
       # empty one with a failed success code.
       def self.geocode(address)  
         res = do_geocode(address)
-        return res.success? ? res : GeoLoc.new
+        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.
@@ -298,6 +313,8 @@ module Geokit
           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 
@@ -441,8 +458,8 @@ module Geokit
         # 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"]']
-        accuracy = address_details ? address_details.attributes['Accuracy'].to_i : 0
-        res.precision=%w{unknown country state state city zip zip+4 street address building}[accuracy]
+        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        
@@ -463,7 +480,7 @@ module Geokit
         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 GeloPluginGeocoder geocoding call: "+$!
+        logger.error "Caught an error during GeoPluginGeocoder geocoding call: "+$!
         return GeoLoc.new
       end
 
@@ -476,7 +493,7 @@ module Geokit
         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.empty?
+        geo.success = !!geo.city && !geo.city.empty?
         return geo
       end
     end
@@ -529,7 +546,8 @@ module Geokit
     # -------------------------------------------------------------------------------------------    
     
     # Provides methods to geocode with a variety of geocoding service providers, plus failover
-    # among providers in the order you configure.
+    # 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
@@ -537,18 +555,21 @@ module Geokit
     # 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
+    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)
-        Geokit::Geocoders::provider_order.each do |provider|
+        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 "#{provider.to_s.capitalize}Geocoder"
+            klass = Geokit::Geocoders.const_get "#{Geokit::Inflector::camelize(provider.to_s)}Geocoder"
             res = klass.send :geocode, address
             return res if res.success?
           rescue

data/lib/geokit/mappable.rb

@@ -251,6 +251,14 @@ module Geokit
       other.is_a?(LatLng) ? self.lat == other.lat && self.lng == other.lng : false
     end
     
+    def hash
+      lat.hash + lng.hash
+    end
+    
+    def eql?(other)
+      self == other
+    end
+    
     # A *class* method to take anything which can be inferred as a point and generate
     # a LatLng from it. You should use this anything you're not sure what the input is,
     # and want to deal with it as a LatLng if at all possible. Can take:
@@ -317,6 +325,9 @@ module Geokit
     attr_accessor :success, :provider, :precision
     # Street number and street name are extracted from the street address attribute.
     attr_reader :street_number, :street_name
+    # accuracy is set for Yahoo and Google geocoders, it is a numeric value of the 
+    # precision. see http://code.google.com/apis/maps/documentation/geocoding/#GeocodingAccuracy
+    attr_accessor :accuracy
 
     # Constructor expects a hash of symbols to correspond with attributes.
     def initialize(h={})
@@ -392,7 +403,7 @@ module Geokit
 
     # Returns a string representation of the instance.
     def to_s
-      "Provider: #{provider}\n Street: #{street_address}\nCity: #{city}\nState: #{state}\nZip: #{zip}\nLatitude: #{lat}\nLongitude: #{lng}\nCountry: #{country_code}\nSuccess: #{success}"
+      "Provider: #{provider}\nStreet: #{street_address}\nCity: #{city}\nState: #{state}\nZip: #{zip}\nLatitude: #{lat}\nLongitude: #{lng}\nCountry: #{country_code}\nSuccess: #{success}"
     end
   end
   

data/test/test_google_geocoder.rb

@@ -50,6 +50,15 @@ class GoogleGeocoderTest < BaseGeocoderTest #:nodoc: all
     assert_equal "100 Spear St, San Francisco, CA 94105, USA", res.full_address #slightly different from yahoo
     assert_equal "google", res.provider
   end  
+  
+  def test_google_full_address_accuracy
+    response = MockSuccess.new
+    response.expects(:body).returns(GOOGLE_FULL)
+    url = "http://maps.google.com/maps/geo?q=#{Geokit::Inflector.url_escape(@full_address_short_zip)}&output=xml&key=Google&oe=utf-8"
+    Geokit::Geocoders::GoogleGeocoder.expects(:call_geocoder_service).with(url).returns(response)
+    res=Geokit::Geocoders::GoogleGeocoder.geocode(@google_full_loc)
+    assert_equal 8, res.accuracy
+  end
 
   def test_google_city
     response = MockSuccess.new
@@ -66,6 +75,15 @@ class GoogleGeocoderTest < BaseGeocoderTest #:nodoc: all
     assert_equal "google", res.provider
   end  
   
+  def test_google_city_accuracy
+    response = MockSuccess.new
+    response.expects(:body).returns(GOOGLE_CITY)
+    url = "http://maps.google.com/maps/geo?q=#{Geokit::Inflector.url_escape(@address)}&output=xml&key=Google&oe=utf-8"
+    Geokit::Geocoders::GoogleGeocoder.expects(:call_geocoder_service).with(url).returns(response)
+    res=Geokit::Geocoders::GoogleGeocoder.geocode(@address)
+    assert_equal 4, res.accuracy
+  end
+  
   def test_google_city_with_geo_loc
     response = MockSuccess.new
     response.expects(:body).returns(GOOGLE_CITY)

data/test/test_latlng.rb

@@ -128,5 +128,21 @@ class LatLngTest < Test::Unit::TestCase #:nodoc: all
     res=Geokit::LatLng.normalize([lat,lng])
     assert_equal res,Geokit::LatLng.new(lat,lng)
   end
-    
+  
+  def test_hash
+    lat=37.7690
+    lng=-122.443
+    first = Geokit::LatLng.new(lat,lng)
+    second = Geokit::LatLng.new(lat,lng)
+    assert_equal first.hash, second.hash
+  end
+  
+  def test_eql?
+    lat=37.7690
+    lng=-122.443
+    first = Geokit::LatLng.new(lat,lng)
+    second = Geokit::LatLng.new(lat,lng)
+    assert first.eql?(second)
+    assert second.eql?(first)
+  end
 end

data/test/test_yahoo_geocoder.rb

@@ -32,6 +32,15 @@ class YahooGeocoderTest < BaseGeocoderTest #:nodoc: all
     do_full_address_assertions(Geokit::Geocoders::YahooGeocoder.geocode(@address))
   end 
   
+  def test_yahoo_full_address_accuracy
+    response = MockSuccess.new
+    response.expects(:body).returns(YAHOO_FULL)
+    url = "http://api.local.yahoo.com/MapsService/V1/geocode?appid=Yahoo&location=#{Geokit::Inflector.url_escape(@address)}"
+    Geokit::Geocoders::YahooGeocoder.expects(:call_geocoder_service).with(url).returns(response)
+    res = Geokit::Geocoders::YahooGeocoder.geocode(@address)
+    assert_equal 8, res.accuracy
+  end
+  
   def test_yahoo_full_address_with_geo_loc
     response = MockSuccess.new
     response.expects(:body).returns(YAHOO_FULL)
@@ -48,6 +57,15 @@ class YahooGeocoderTest < BaseGeocoderTest #:nodoc: all
     do_city_assertions(Geokit::Geocoders::YahooGeocoder.geocode(@address))
   end
   
+  def test_yahoo_city_accuracy
+    response = MockSuccess.new
+    response.expects(:body).returns(YAHOO_CITY)
+    url = "http://api.local.yahoo.com/MapsService/V1/geocode?appid=Yahoo&location=#{Geokit::Inflector.url_escape(@address)}"
+    Geokit::Geocoders::YahooGeocoder.expects(:call_geocoder_service).with(url).returns(response)
+    res = Geokit::Geocoders::YahooGeocoder.geocode(@address)
+    assert_equal 4, res.accuracy
+  end
+  
   def test_yahoo_city_with_geo_loc
     response = MockSuccess.new
     response.expects(:body).returns(YAHOO_CITY)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: andre-geokit
 version: !ruby/object:Gem::Version 
-  version: 1.2.6
+  version: 1.3.1
 platform: ruby
 authors: 
 - Andre Lewis and Bill Eisenhauer
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-02-09 00:00:00 -08:00
+date: 2009-04-11 00:00:00 -07:00
 default_executable: 
 dependencies: []