geokit 1.3.2 → 1.4.0

data/History.txt

@@ -1,3 +1,8 @@
+=== 1.4.0 / 2009-05-27
+* Added country code/viewport biasing to GoogleGeocoder. Added Bounds#to_span method
+* Added suggested_bounds (Geokit::Bounds) property to GeoLoc. (Google geocoder only)
+* Added LatLng#reverse_geocode convenience method (thanks Tisho Georgiev for all three)
+
 === 1.3.2 / 2009-05-27
 * Fixed blank address geocoding bug
 

data/README.markdown

@@ -124,12 +124,48 @@ creates a template with these settings and places it in `config/initializers/geo
 * Geonames - a free geocoder
 
 ### address geocoders that also provide reverse geocoding 
-* Google Geocoder - requires an API key. Also supports multiple results.
+* Google Geocoder - requires an API key. Also supports multiple results and bounding box/country code biasing.
 
 ### IP address geocoders 
 * IP Geocoder - geocodes an IP address using hostip.info's web service.
 * Geoplugin.net -- another IP address geocoder
 
+### Google Geocoder Tricks
+
+The Google Geocoder sports a number of useful tricks that elevate it a little bit above the rest of the currently supported geocoders. For starters, it returns a `suggested_bounds` property for all your geocoded results, so you can more easily decide where and how to center a map on the places you geocode. Here's a quick example:
+
+    irb> res = Geokit::Geocoders::GoogleGeocoder.geocode('140 Market St, San Francisco, CA')
+		irb> pp res.suggested_bounds
+		#<Geokit::Bounds:0x53b36c
+		 @ne=#<Geokit::LatLng:0x53b204 @lat=37.7968528, @lng=-122.3926933>,
+		 @sw=#<Geokit::LatLng:0x53b2b8 @lat=37.7905576, @lng=-122.3989885>>
+
+In addition, you can use viewport or country code biasing to make sure the geocoders prefers results within a specific area. Say we wanted to geocode the city of Syracuse in Italy. A normal geocoding query would look like this:
+
+		irb> res = Geokit::Geocoder::GoogleGeocoder.geocode('Syracuse')
+		irb> res.full_address
+		=> "Syracuse, NY, USA"
+	
+Not exactly what we were looking for. We know that Syracuse is in Italy, so we can tell the Google Geocoder to prefer results from Italy first, and then wander the Syracuses of the world. To do that, we have to pass Italy's ccTLD (country code top-level domain) to the `:bias` option of the `geocode` method. You can find a comprehensive list of all ccTLDs here: http://en.wikipedia.org/wiki/CcTLD.
+
+		irb> res = Geokit::Geocoder::GoogleGeocoder.geocode('Syracuse', :bias => 'it')
+		irb> res.full_address
+		=> "Syracuse, Italy"
+
+Alternatively, we can speficy the geocoding bias as a bounding box object. Say we wanted to geocode the Winnetka district in Los Angeles.
+
+		irb> res = Geokit::Geocoder::GoogleGeocoder.geocode('Winnetka')
+		irb> res.full_address
+		=> "Winnetka, IL, USA"
+	
+Not it. What we can do is tell the geocoder to return results only from in and around LA.
+
+		irb> la_bounds = Geokit::Geocoder::GoogleGeocoder.geocode('Los Angeles').suggested_bounds
+		irb> res = Geokit::Geocoder::GoogleGeocoder.geocode('Winnetka', :bias => la_bounds)
+		irb> res.full_address
+		=> "Winnetka, California, USA"
+
+
 ### 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:
 
@@ -195,7 +231,7 @@ You must then also require such extenal file back in your main geokit configurat
 		# and use :external to specify this geocoder in your list of geocoders.
 	    class ExternalGeocoder < Geocoder
 	      private 
-	      def self.do_geocode(address)
+	      def self.do_geocode(address, options = {})
 	        # Main geocoding method
 	      end
 

data/geokit.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{geokit}
-  s.version = "1.3.2"
+  s.version = "1.4.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Andre Lewis and Bill Eisenhauer"]

data/lib/geokit.rb

@@ -1,5 +1,5 @@
 module Geokit
-  VERSION = '1.3.2'
+  VERSION = '1.4.0'
   # 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

@@ -119,8 +119,8 @@ module Geokit
       # 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)
+      def self.geocode(address, options = {}) 
+        res = do_geocode(address, options)
         return res.nil? ? GeoLoc.new : res
       end  
       # Main method which calls the do_reverse_geocode template method which subclasses
@@ -172,8 +172,8 @@ module Geokit
       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)
+          def self.#{Geokit::Inflector.underscore(class_name)}(address, options = {})
+            #{class_name}.geocode(address, options)
           end
         END_SRC
         class_eval(src)
@@ -199,7 +199,7 @@ module Geokit
       private
 
       # Template method which does the geocode lookup.
-      def self.do_geocode(address)
+      def self.do_geocode(address, options = {})
         raise ArgumentError('Geocoder.ca requires a GeoLoc argument') unless address.is_a?(GeoLoc)
         url = construct_request(address)
         res = self.call_geocoder_service(url)
@@ -241,7 +241,7 @@ module Geokit
     class UsGeocoder < Geocoder
 
       private
-      def self.do_geocode(address)
+      def self.do_geocode(address, options = {})
         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)}"
@@ -289,7 +289,7 @@ module Geokit
       private 
 
       # Template method which does the geocode lookup.
-      def self.do_geocode(address)
+      def self.do_geocode(address, options = {})
         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)
@@ -335,7 +335,7 @@ module Geokit
       private 
       
       # Template method which does the geocode lookup.
-      def self.do_geocode(address)
+      def self.do_geocode(address, options = {})
         address_str = address.is_a?(GeoLoc) ? address.to_geocodeable_s : address
         # geonames need a space seperated search string
         address_str.gsub!(/,/, " ")
@@ -400,15 +400,50 @@ module Geokit
       end  
 
       # Template method which does the geocode lookup.
-      def self.do_geocode(address)
+      #
+      # Supports viewport/country code biasing
+      #
+      # ==== OPTIONS
+      # * :bias - This option makes the Google Geocoder return results biased to a particular
+      #           country or viewport. Country code biasing is achieved by passing the ccTLD
+      #           ('uk' for .co.uk, for example) as a :bias value. For a list of ccTLD's, 
+      #           look here: http://en.wikipedia.org/wiki/CcTLD. By default, the geocoder
+      #           will be biased to results within the US (ccTLD .com).
+      #
+      #           If you'd like the Google Geocoder to prefer results within a given viewport,
+      #           you can pass a Geokit::Bounds object as the :bias value.
+      #
+      # ==== EXAMPLES
+      # # By default, the geocoder will return Syracuse, NY
+      # Geokit::Geocoders::GoogleGeocoder.geocode('Syracuse').country_code # => 'US'
+      # # With country code biasing, it returns Syracuse in Sicily, Italy
+      # Geokit::Geocoders::GoogleGeocoder.geocode('Syracuse', :bias => :it).country_code # => 'IT'
+      #
+      # # By default, the geocoder will return Winnetka, IL
+      # Geokit::Geocoders::GoogleGeocoder.geocode('Winnetka').state # => 'IL'
+      # # When biased to an bounding box around California, it will now return the Winnetka neighbourhood, CA
+      # bounds = Geokit::Bounds.normalize([34.074081, -118.694401], [34.321129, -118.399487])
+      # Geokit::Geocoders::GoogleGeocoder.geocode('Winnetka', :bias => bounds).state # => 'CA'
+      def self.do_geocode(address, options = {})
+        bias_str = options[:bias] ? construct_bias_string_from_options(options[:bias]) : ''
         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")
+        res = self.call_geocoder_service("http://maps.google.com/maps/geo?q=#{Geokit::Inflector::url_escape(address_str)}&output=xml#{bias_str}&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.construct_bias_string_from_options(bias)
+        if bias.is_a?(String) or bias.is_a?(Symbol)
+          # country code biasing
+          "&gl=#{bias.to_s.downcase}"
+        elsif bias.is_a?(Bounds)
+          # viewport biasing
+          "&ll=#{bias.center.ll}&spn=#{bias.to_span.ll}"
+        end
+      end
+      
       def self.xml2GeoLoc(xml, address="")
         doc=REXML::Document.new(xml)
 
@@ -460,6 +495,14 @@ module Geokit
         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]
+        
+        # google returns a set of suggested boundaries for the geocoded result
+        if suggested_bounds = doc.elements['//LatLonBox']  
+          res.suggested_bounds = Bounds.normalize(
+                                  [suggested_bounds.attributes['south'], suggested_bounds.attributes['west']], 
+                                  [suggested_bounds.attributes['north'], suggested_bounds.attributes['east']])
+        end
+        
         res.success=true
         
         return res        
@@ -475,7 +518,7 @@ module Geokit
     class GeoPluginGeocoder < Geocoder
       private
       
-      def self.do_geocode(ip)
+      def self.do_geocode(ip, options = {})
         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
@@ -508,7 +551,7 @@ module Geokit
       # 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)
+      def self.do_geocode(ip, options = {})
         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"
@@ -563,14 +606,14 @@ module Geokit
       # 
       # 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)
+      def self.do_geocode(address, options = {})
         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
+            res = klass.send :geocode, address, options
             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}")
@@ -579,6 +622,23 @@ module Geokit
         # If we get here, we failed completely.
         GeoLoc.new
       end
+      
+      # This method will call one or more geocoders in the order specified in the 
+      # configuration until one of the geocoders work, only this time it's going
+      # to try to reverse geocode a geographical point.
+      def self.do_reverse_geocode(latlng)
+        Geokit::Geocoders::provider_order.each do |provider|
+          begin
+            klass = Geokit::Geocoders.const_get "#{Geokit::Inflector::camelize(provider.to_s)}Geocoder"
+            res = klass.send :reverse_geocode, latlng
+            return res if res.success?
+          rescue
+            logger.error("Something has gone very wrong during reverse geocoding, OR you have configured an invalid class name in Geokit::Geocoders::provider_order. LatLng: #{latlng}. Provider: #{provider}")
+          end
+        end
+        # If we get here, we failed completely.
+        GeoLoc.new
+      end
     end   
   end
 end

data/lib/geokit/mappable.rb

@@ -110,8 +110,8 @@ module Geokit
       end
   
       # Geocodes a location using the multi geocoder.
-      def geocode(location)
-        res = Geocoders::MultiGeocoder.geocode(location)
+      def geocode(location, options = {})
+        res = Geocoders::MultiGeocoder.geocode(location, options)
         return res if res.success?
         raise Geokit::Geocoders::GeocodeError      
       end
@@ -292,6 +292,30 @@ module Geokit
       raise ArgumentError.new("#{thing} (#{thing.class}) cannot be normalized to a LatLng. We tried interpreting it as an array, string, Mappable, etc., but no dice.")
     end
     
+    # Reverse geocodes a LatLng object using the MultiGeocoder (default), or optionally
+    # using a geocoder of your choosing. Returns a new Geokit::GeoLoc object
+    # 
+    # ==== Options
+    # * :using  - Specifies the geocoder to use for reverse geocoding. Defaults to
+    #             MultiGeocoder. Can be either the geocoder class (or any class that 
+    #             implements do_reverse_geocode for that matter), or the name of
+    #             the class without the "Geocoder" part (e.g. :google)
+    #
+    # ==== Examples
+    # LatLng.new(51.4578329, 7.0166848).reverse_geocode # => #<Geokit::GeoLoc:0x12dac20 @state...>
+    # LatLng.new(51.4578329, 7.0166848).reverse_geocode(:using => :google) # => #<Geokit::GeoLoc:0x12dac20 @state...>
+    # LatLng.new(51.4578329, 7.0166848).reverse_geocode(:using => Geokit::Geocoders::GoogleGeocoder) # => #<Geokit::GeoLoc:0x12dac20 @state...>
+    def reverse_geocode(options = { :using => Geokit::Geocoders::MultiGeocoder })
+      if options[:using].is_a?(String) or options[:using].is_a?(Symbol)
+        provider = Geokit::Geocoders.const_get("#{Geokit::Inflector::camelize(options[:using].to_s)}Geocoder")
+      elsif options[:using].respond_to?(:do_reverse_geocode)
+        provider = options[:using]
+      else
+        raise ArgumentError.new("#{options[:using]} is not a valid geocoder.")
+      end
+      
+      provider.send(:reverse_geocode, self)
+    end
   end
 
   # This class encapsulates the result of a geocoding call.
@@ -322,7 +346,7 @@ module Geokit
     # Attributes set upon return from geocoding.  Success will be true for successful
     # geocode lookups.  The provider will be set to the name of the providing geocoder.
     # Finally, precision is an indicator of the accuracy of the geocoding.
-    attr_accessor :success, :provider, :precision
+    attr_accessor :success, :provider, :precision, :suggested_bounds
     # 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 
@@ -387,8 +411,8 @@ module Geokit
     # Sets the street address after capitalizing each word within the street address.
     def street_address=(address)
       @street_address = Geokit::Inflector::titleize(address) if address
-    end  
-
+    end
+    
     # Returns a comma-delimited string consisting of the street address, city, state,
     # zip, and country code.  Only includes those attributes that are non-blank.
     def to_geocodeable_s
@@ -457,6 +481,16 @@ module Geokit
       other.is_a?(Bounds) ? self.sw == other.sw && self.ne == other.ne : false
     end
     
+    # Equivalent to Google Maps API's .toSpan() method on GLatLng's.
+    #
+    # Returns a LatLng object, whose coordinates represent the size of a rectangle
+    # defined by these bounds.
+    def to_span
+      lat_span = (@ne.lat - @sw.lat).abs
+      lng_span = (crosses_meridian? ? 360 + @ne.lng - @sw.lng : @ne.lng - @sw.lng).abs
+      Geokit::LatLng.new(lat_span, lng_span)
+    end
+    
     class <<self
       
       # returns an instance of bounds which completely encompases the given circle

data/test/test_base_geocoder.rb

@@ -29,7 +29,8 @@ class BaseGeocoderTest < Test::Unit::TestCase #:nodoc: all
     @full_address = '100 Spear St, San Francisco, CA, 94105-1522, US'   
     @full_address_short_zip = '100 Spear St, San Francisco, CA, 94105, US' 
     
-    @success = Geokit::GeoLoc.new({:city=>"SAN FRANCISCO", :state=>"CA", :country_code=>"US", :lat=>37.7742, :lng=>-122.417068})
+    @latlng = Geokit::LatLng.new(37.7742, -122.417068)
+    @success = Geokit::GeoLoc.new({:city=>"SAN FRANCISCO", :state=>"CA", :country_code=>"US", :lat=>@latlng.lat, :lng=>@latlng.lng})
     @success.success = true    
   end  
   

data/test/test_bounds.rb

@@ -71,4 +71,27 @@ class BoundsTest < Test::Unit::TestCase #:nodoc: all
     assert !bounds.contains?(outside)
   end
   
+  def test_bounds_to_span
+    sw = Geokit::LatLng.new(32, -96)
+    ne = Geokit::LatLng.new(40, -70)
+    bounds = Geokit::Bounds.new(sw, ne)
+    
+    assert_equal Geokit::LatLng.new(8, 26), bounds.to_span
+  end
+  
+  def test_bounds_to_span_with_bounds_crossing_prime_meridian
+    sw = Geokit::LatLng.new(20, -70)
+    ne = Geokit::LatLng.new(40, 100)
+    bounds = Geokit::Bounds.new(sw, ne)
+    
+    assert_equal Geokit::LatLng.new(20, 170), bounds.to_span
+  end
+  
+  def test_bounds_to_span_with_bounds_crossing_dateline
+    sw = Geokit::LatLng.new(20, 100)
+    ne = Geokit::LatLng.new(40, -70)
+    bounds = Geokit::Bounds.new(sw, ne)
+    
+    assert_equal Geokit::LatLng.new(20, 190), bounds.to_span
+  end
 end

data/test/test_google_geocoder.rb

@@ -7,6 +7,10 @@ class GoogleGeocoderTest < BaseGeocoderTest #:nodoc: all
   GOOGLE_FULL=<<-EOF.strip
   <?xml version="1.0" encoding="UTF-8"?><kml xmlns="http://earth.google.com/kml/2.0"><Response><name>100 spear st, san francisco, ca</name><Status><code>200</code><request>geocode</request></Status><Placemark><address>100 Spear St, San Francisco, CA 94105, USA</address><AddressDetails Accuracy="8" xmlns="urn:oasis:names:tc:ciq:xsdschema:xAL:2.0"><Country><CountryNameCode>US</CountryNameCode><AdministrativeArea><AdministrativeAreaName>CA</AdministrativeAreaName><SubAdministrativeArea><SubAdministrativeAreaName>San Francisco</SubAdministrativeAreaName><Locality><LocalityName>San Francisco</LocalityName><Thoroughfare><ThoroughfareName>100 Spear St</ThoroughfareName></Thoroughfare><PostalCode><PostalCodeNumber>94105</PostalCodeNumber></PostalCode></Locality></SubAdministrativeArea></AdministrativeArea></Country></AddressDetails><Point><coordinates>-122.393985,37.792501,0</coordinates></Point></Placemark></Response></kml>
   EOF
+  
+  GOOGLE_RESULT_WITH_SUGGESTED_BOUNDS=<<-EOF.strip
+  <?xml version="1.0" encoding="UTF-8"?><kml xmlns="http://earth.google.com/kml/2.0"><Response><name>100 spear st, san francisco, ca</name><Status><code>200</code><request>geocode</request></Status><Placemark><address>100 Spear St, San Francisco, CA 94105, USA</address><AddressDetails Accuracy="8" xmlns="urn:oasis:names:tc:ciq:xsdschema:xAL:2.0"><Country><CountryNameCode>US</CountryNameCode><AdministrativeArea><AdministrativeAreaName>CA</AdministrativeAreaName><SubAdministrativeArea><SubAdministrativeAreaName>San Francisco</SubAdministrativeAreaName><Locality><LocalityName>San Francisco</LocalityName><Thoroughfare><ThoroughfareName>100 Spear St</ThoroughfareName></Thoroughfare><PostalCode><PostalCodeNumber>94105</PostalCodeNumber></PostalCode></Locality></SubAdministrativeArea></AdministrativeArea></Country></AddressDetails><ExtendedData><LatLonBox north="37.7956328" south="37.7893376" east="-122.3908573" west="-122.3971525" /></ExtendedData><Point><coordinates>-122.393985,37.792501,0</coordinates></Point></Placemark></Response></kml>
+  EOF
 
   GOOGLE_CITY=<<-EOF.strip
   <?xml version="1.0" encoding="UTF-8"?><kml xmlns="http://earth.google.com/kml/2.0"><Response><name>San Francisco</name><Status><code>200</code><request>geocode</request></Status><Placemark><address>San Francisco, CA, USA</address><AddressDetails Accuracy="4" xmlns="urn:oasis:names:tc:ciq:xsdschema:xAL:2.0"><Country><CountryNameCode>US</CountryNameCode><AdministrativeArea><AdministrativeAreaName>CA</AdministrativeAreaName><Locality><LocalityName>San Francisco</LocalityName></Locality></AdministrativeArea></Country></AddressDetails><Point><coordinates>-122.418333,37.775000,0</coordinates></Point></Placemark></Response></kml>
@@ -14,6 +18,14 @@ class GoogleGeocoderTest < BaseGeocoderTest #:nodoc: all
   
   GOOGLE_MULTI="<?xml version='1.0' encoding='UTF-8'?>\n<kml xmlns='http://earth.google.com/kml/2.0'><Response>\n  <name>via Sandro Pertini 8, Ossona, MI</name>\n  <Status>\n    <code>200</code>\n    <request>geocode</request>\n  </Status>\n  <Placemark id='p1'>\n    <address>Via Sandro Pertini, 8, 20010 Mesero MI, Italy</address>\n    <AddressDetails Accuracy='8' xmlns='urn:oasis:names:tc:ciq:xsdschema:xAL:2.0'><Country><CountryNameCode>IT</CountryNameCode><CountryName>Italy</CountryName><AdministrativeArea><AdministrativeAreaName>Lombardy</AdministrativeAreaName><SubAdministrativeArea><SubAdministrativeAreaName>Milan</SubAdministrativeAreaName><Locality><LocalityName>Mesero</LocalityName><Thoroughfare><ThoroughfareName>8 Via Sandro Pertini</ThoroughfareName></Thoroughfare><PostalCode><PostalCodeNumber>20010</PostalCodeNumber></PostalCode></Locality></SubAdministrativeArea></AdministrativeArea></Country></AddressDetails>\n    <Point><coordinates>8.8527131,45.4966243,0</coordinates></Point>\n  </Placemark>\n  <Placemark id='p2'>\n    <address>Via Sandro Pertini, 20010 Ossona MI, Italy</address>\n    <AddressDetails Accuracy='6' xmlns='urn:oasis:names:tc:ciq:xsdschema:xAL:2.0'><Country><CountryNameCode>IT</CountryNameCode><CountryName>Italy</CountryName><AdministrativeArea><AdministrativeAreaName>Lombardy</AdministrativeAreaName><SubAdministrativeArea><SubAdministrativeAreaName>Milan</SubAdministrativeAreaName><Locality><LocalityName>Ossona</LocalityName><Thoroughfare><ThoroughfareName>Via Sandro Pertini</ThoroughfareName></Thoroughfare><PostalCode><PostalCodeNumber>20010</PostalCodeNumber></PostalCode></Locality></SubAdministrativeArea></AdministrativeArea></Country></AddressDetails>\n    <Point><coordinates>8.9023200,45.5074444,0</coordinates></Point>\n  </Placemark>\n</Response></kml>\n"
   
+  GOOGLE_COUNTRY_CODE_BIASED_RESULT = <<-EOF.strip
+  <?xml version="1.0" encoding="UTF-8" ?><kml xmlns="http://earth.google.com/kml/2.0"><Response><name>Syracuse</name><Status><code>200</code><request>geocode</request></Status><Placemark id="p1"><address>Syracuse, Italy</address><AddressDetails Accuracy="3" xmlns="urn:oasis:names:tc:ciq:xsdschema:xAL:2.0"><Country><CountryNameCode>IT</CountryNameCode><CountryName>Italy</CountryName><AdministrativeArea><AdministrativeAreaName>Sicily</AdministrativeAreaName><SubAdministrativeArea><SubAdministrativeAreaName>Syracuse</SubAdministrativeAreaName></SubAdministrativeArea></AdministrativeArea></Country></AddressDetails><ExtendedData><LatLonBox north="37.4125978" south="36.6441736" east="15.3367367" west="14.7724913" /></ExtendedData><Point><coordinates>14.9856176,37.0630218,0</coordinates></Point></Placemark></Response></kml>
+  EOF
+  
+  GOOGLE_BOUNDS_BIASED_RESULT = <<-EOF.strip
+  <?xml version="1.0" encoding="UTF-8" ?><kml xmlns="http://earth.google.com/kml/2.0"><Response><name>Winnetka</name><Status><code>200</code><request>geocode</request></Status><Placemark id="p1"><address>Winnetka, California, USA</address><AddressDetails Accuracy="4" xmlns="urn:oasis:names:tc:ciq:xsdschema:xAL:2.0"><Country><CountryNameCode>US</CountryNameCode><CountryName>USA</CountryName><AdministrativeArea><AdministrativeAreaName>CA</AdministrativeAreaName><AddressLine>Winnetka</AddressLine></AdministrativeArea></Country></AddressDetails><ExtendedData><LatLonBox north="34.2353090" south="34.1791050" east="-118.5534191" west="-118.5883200" /></ExtendedData><Point><coordinates>-118.5710220,34.2131710,0</coordinates></Point></Placemark></Response></kml>
+  EOF
+  
   def setup
     super
     @google_full_hash = {:street_address=>"100 Spear St", :city=>"San Francisco", :state=>"CA", :zip=>"94105", :country_code=>"US"}
@@ -99,6 +111,17 @@ class GoogleGeocoderTest < BaseGeocoderTest #:nodoc: all
     assert_equal "google", res.provider
   end  
   
+  def test_google_suggested_bounds
+    response = MockSuccess.new
+    response.expects(:body).returns(GOOGLE_RESULT_WITH_SUGGESTED_BOUNDS)
+    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_instance_of Geokit::Bounds, res.suggested_bounds
+    assert_equal Geokit::Bounds.new(Geokit::LatLng.new(37.7893376, -122.3971525), Geokit::LatLng.new(37.7956328, -122.3908573)), res.suggested_bounds
+  end
+  
   def test_service_unavailable
     response = MockFailure.new
     url = "http://maps.google.com/maps/geo?q=#{Geokit::Inflector.url_escape(@address)}&output=xml&key=Google&oe=utf-8"
@@ -131,4 +154,30 @@ class GoogleGeocoderTest < BaseGeocoderTest #:nodoc: all
     assert_equal "Via Sandro Pertini", res.street_address
     assert_equal "google", res.provider
   end
+  
+  def test_country_code_biasing
+    response = MockSuccess.new
+    response.expects(:body).returns(GOOGLE_COUNTRY_CODE_BIASED_RESULT)
+    
+    url = "http://maps.google.com/maps/geo?q=Syracuse&output=xml&gl=it&key=Google&oe=utf-8"
+    Geokit::Geocoders::GoogleGeocoder.expects(:call_geocoder_service).with(url).returns(response)
+    biased_result = Geokit::Geocoders::GoogleGeocoder.geocode('Syracuse', :bias => 'it')
+    
+    assert_equal 'IT', biased_result.country_code
+    assert_equal 'Sicily', biased_result.state
+  end
+  
+  def test_bounds_biasing
+    response = MockSuccess.new
+    response.expects(:body).returns(GOOGLE_BOUNDS_BIASED_RESULT)
+    
+    url = "http://maps.google.com/maps/geo?q=Winnetka&output=xml&ll=34.197693208849,-118.547160027785&spn=0.247047999999999,0.294914000000006&key=Google&oe=utf-8"
+    Geokit::Geocoders::GoogleGeocoder.expects(:call_geocoder_service).with(url).returns(response)
+    
+    bounds = Geokit::Bounds.normalize([34.074081, -118.694401], [34.321129, -118.399487])
+    biased_result = Geokit::Geocoders::GoogleGeocoder.geocode('Winnetka', :bias => bounds)
+    
+    assert_equal 'US', biased_result.country_code
+    assert_equal 'CA', biased_result.state
+  end
 end

data/test/test_latlng.rb

@@ -1,5 +1,6 @@
 require 'test/unit'
 require 'lib/geokit'
+require 'mocha'
 
 class LatLngTest < Test::Unit::TestCase #:nodoc: all
   
@@ -9,6 +10,25 @@ class LatLngTest < Test::Unit::TestCase #:nodoc: all
     @point = Geokit::LatLng.new(@loc_a.lat, @loc_a.lng)
   end
   
+  def valid_reverse_geocoding_result
+    location = Geokit::GeoLoc.new({
+      :city => "Essen",
+      :country_code => "DE",
+      :lat => 51.4578329,
+      :lng => 7.0166848,
+      :provider => "google",
+      :state => "Nordrhein-Westfalen",
+      :street_address => "Porscheplatz 1",
+      :zip => "45127"
+    })
+    
+    location.full_address = "Porscheplatz 1, 45127 Essen, Deutschland"
+    location.precision = 'address'
+    location.provider = 'google'
+    location.success = true
+    location
+  end
+  
   def test_distance_between_same_using_defaults
     assert_equal 0, Geokit::LatLng.distance_between(@loc_a, @loc_a)
     assert_equal 0, @loc_a.distance_to(@loc_a)
@@ -145,4 +165,45 @@ class LatLngTest < Test::Unit::TestCase #:nodoc: all
     assert first.eql?(second)
     assert second.eql?(first)
   end
+  
+  def test_reverse_geocode
+    point = Geokit::LatLng.new(51.4578329, 7.0166848)
+    Geokit::Geocoders::MultiGeocoder.expects(:reverse_geocode).with(point).returns(valid_reverse_geocoding_result)
+    res = point.reverse_geocode
+    
+    assert_equal "Nordrhein-Westfalen", res.state
+    assert_equal "Essen", res.city 
+    assert_equal "45127", res.zip
+    assert_equal "51.4578329,7.0166848", res.ll # slightly dif from yahoo
+    assert res.is_us? == false
+    assert_equal "Porscheplatz 1, 45127 Essen, Deutschland", res.full_address #slightly different from yahoo
+  end
+  
+  def test_reverse_geocoding_using_specific_geocoder
+    point = Geokit::LatLng.new(51.4578329, 7.0166848)
+    Geokit::Geocoders::GoogleGeocoder.expects(:reverse_geocode).with(point).returns(valid_reverse_geocoding_result)
+    res = point.reverse_geocode(:using => Geokit::Geocoders::GoogleGeocoder)
+
+    assert_equal "Nordrhein-Westfalen", res.state
+    assert_equal "Essen", res.city 
+    assert_equal "45127", res.zip
+    assert_equal "51.4578329,7.0166848", res.ll # slightly dif from yahoo
+    assert res.is_us? == false
+    assert_equal "Porscheplatz 1, 45127 Essen, Deutschland", res.full_address #slightly different from yahoo
+    assert_equal "google", res.provider
+  end
+  
+  def test_reverse_geocoding_using_specific_geocoder_short_syntax
+    point = Geokit::LatLng.new(51.4578329, 7.0166848)
+    Geokit::Geocoders::GoogleGeocoder.expects(:reverse_geocode).with(point).returns(valid_reverse_geocoding_result)
+    res = point.reverse_geocode(:using => :google)
+
+    assert_equal "Nordrhein-Westfalen", res.state
+    assert_equal "Essen", res.city 
+    assert_equal "45127", res.zip
+    assert_equal "51.4578329,7.0166848", res.ll # slightly dif from yahoo
+    assert res.is_us? == false
+    assert_equal "Porscheplatz 1, 45127 Essen, Deutschland", res.full_address #slightly different from yahoo
+    assert_equal "google", res.provider
+  end
 end

data/test/test_multi_geocoder.rb

@@ -10,27 +10,27 @@ class MultiGeocoderTest < BaseGeocoderTest #:nodoc: all
   end
   
   def test_successful_first
-    Geokit::Geocoders::GoogleGeocoder.expects(:geocode).with(@address).returns(@success)
+    Geokit::Geocoders::GoogleGeocoder.expects(:geocode).with(@address, {}).returns(@success)
     assert_equal @success, Geokit::Geocoders::MultiGeocoder.geocode(@address)
   end
   
   def test_failover
-    Geokit::Geocoders::GoogleGeocoder.expects(:geocode).with(@address).returns(@failure)
-    Geokit::Geocoders::YahooGeocoder.expects(:geocode).with(@address).returns(@success)
+    Geokit::Geocoders::GoogleGeocoder.expects(:geocode).with(@address, {}).returns(@failure)
+    Geokit::Geocoders::YahooGeocoder.expects(:geocode).with(@address, {}).returns(@success)
     assert_equal @success, Geokit::Geocoders::MultiGeocoder.geocode(@address)    
   end
   
   def test_double_failover
-    Geokit::Geocoders::GoogleGeocoder.expects(:geocode).with(@address).returns(@failure)
-    Geokit::Geocoders::YahooGeocoder.expects(:geocode).with(@address).returns(@failure)
-    Geokit::Geocoders::UsGeocoder.expects(:geocode).with(@address).returns(@success)
+    Geokit::Geocoders::GoogleGeocoder.expects(:geocode).with(@address, {}).returns(@failure)
+    Geokit::Geocoders::YahooGeocoder.expects(:geocode).with(@address, {}).returns(@failure)
+    Geokit::Geocoders::UsGeocoder.expects(:geocode).with(@address, {}).returns(@success)
     assert_equal @success, Geokit::Geocoders::MultiGeocoder.geocode(@address)    
   end
   
   def test_failure
-    Geokit::Geocoders::GoogleGeocoder.expects(:geocode).with(@address).returns(@failure)
-    Geokit::Geocoders::YahooGeocoder.expects(:geocode).with(@address).returns(@failure)
-    Geokit::Geocoders::UsGeocoder.expects(:geocode).with(@address).returns(@failure)
+    Geokit::Geocoders::GoogleGeocoder.expects(:geocode).with(@address, {}).returns(@failure)
+    Geokit::Geocoders::YahooGeocoder.expects(:geocode).with(@address, {}).returns(@failure)
+    Geokit::Geocoders::UsGeocoder.expects(:geocode).with(@address, {}).returns(@failure)
     assert_equal @failure, Geokit::Geocoders::MultiGeocoder.geocode(@address)    
   end
 
@@ -45,10 +45,49 @@ class MultiGeocoderTest < BaseGeocoderTest #:nodoc: all
     t1, t2 = Geokit::Geocoders.provider_order, Geokit::Geocoders.ip_provider_order # will need to reset after
     Geokit::Geocoders.provider_order = [:google]
     Geokit::Geocoders.ip_provider_order = [:geo_plugin]
-    Geokit::Geocoders::GoogleGeocoder.expects(:geocode).with("").returns(@failure)
+    Geokit::Geocoders::GoogleGeocoder.expects(:geocode).with("", {}).returns(@failure)
     Geokit::Geocoders::GeoPluginGeocoder.expects(:geocode).never
     assert_equal @failure, Geokit::Geocoders::MultiGeocoder.geocode("")
     Geokit::Geocoders.provider_order, Geokit::Geocoders.ip_provider_order = t1, t2 # reset to orig values
   end
 
+  def test_reverse_geocode_successful_first
+    Geokit::Geocoders::GoogleGeocoder.expects(:reverse_geocode).with(@latlng).returns(@success)
+    assert_equal @success, Geokit::Geocoders::MultiGeocoder.reverse_geocode(@latlng)
+  end
+  
+  def test_reverse_geocode_failover
+    Geokit::Geocoders::GoogleGeocoder.expects(:reverse_geocode).with(@latlng).returns(@failure)
+    Geokit::Geocoders::YahooGeocoder.expects(:reverse_geocode).with(@latlng).returns(@success)
+    assert_equal @success, Geokit::Geocoders::MultiGeocoder.reverse_geocode(@latlng)    
+  end
+  
+  def test_reverse_geocode_double_failover
+    Geokit::Geocoders::GoogleGeocoder.expects(:reverse_geocode).with(@latlng).returns(@failure)
+    Geokit::Geocoders::YahooGeocoder.expects(:reverse_geocode).with(@latlng).returns(@failure)
+    Geokit::Geocoders::UsGeocoder.expects(:reverse_geocode).with(@latlng).returns(@success)
+    assert_equal @success, Geokit::Geocoders::MultiGeocoder.reverse_geocode(@latlng)    
+  end
+  
+  def test_reverse_geocode_failure
+    Geokit::Geocoders::GoogleGeocoder.expects(:reverse_geocode).with(@latlng).returns(@failure)
+    Geokit::Geocoders::YahooGeocoder.expects(:reverse_geocode).with(@latlng).returns(@failure)
+    Geokit::Geocoders::UsGeocoder.expects(:reverse_geocode).with(@latlng).returns(@failure)
+    assert_equal @failure, Geokit::Geocoders::MultiGeocoder.reverse_geocode(@latlng)    
+  end
+
+  def test_reverse_geocode_with_invalid_provider
+    temp = Geokit::Geocoders::provider_order
+    Geokit::Geocoders.provider_order = [:bogus]
+    assert_equal @failure, Geokit::Geocoders::MultiGeocoder.reverse_geocode(@latlng)    
+    Geokit::Geocoders.provider_order = temp
+  end
+
+  def test_reverse_geocode_with_blank_latlng
+    t1 = Geokit::Geocoders.provider_order # will need to reset after
+    Geokit::Geocoders.provider_order = [:google]
+    Geokit::Geocoders::GoogleGeocoder.expects(:reverse_geocode).with("").returns(@failure)
+    assert_equal @failure, Geokit::Geocoders::MultiGeocoder.reverse_geocode("")
+    Geokit::Geocoders.provider_order = t1 # reset to orig values
+  end
 end

data/test/test_multi_ip_geocoder.rb

@@ -12,19 +12,19 @@ class MultiIpGeocoderTest < BaseGeocoderTest #:nodoc: all
   end
   
   def test_successful_first
-    Geokit::Geocoders::GeoPluginGeocoder.expects(:geocode).with(@ip_address).returns(@success)
+    Geokit::Geocoders::GeoPluginGeocoder.expects(:geocode).with(@ip_address, {}).returns(@success)
     assert_equal @success, Geokit::Geocoders::MultiGeocoder.geocode(@ip_address)
   end
   
   def test_failover
-    Geokit::Geocoders::GeoPluginGeocoder.expects(:geocode).with(@ip_address).returns(@failure)
-    Geokit::Geocoders::IpGeocoder.expects(:geocode).with(@ip_address).returns(@success)
+    Geokit::Geocoders::GeoPluginGeocoder.expects(:geocode).with(@ip_address, {}).returns(@failure)
+    Geokit::Geocoders::IpGeocoder.expects(:geocode).with(@ip_address, {}).returns(@success)
     assert_equal @success, Geokit::Geocoders::MultiGeocoder.geocode(@ip_address)
   end
   
   def test_failure
-    Geokit::Geocoders::GeoPluginGeocoder.expects(:geocode).with(@ip_address).returns(@failure)
-    Geokit::Geocoders::IpGeocoder.expects(:geocode).with(@ip_address).returns(@failure)
+    Geokit::Geocoders::GeoPluginGeocoder.expects(:geocode).with(@ip_address, {}).returns(@failure)
+    Geokit::Geocoders::IpGeocoder.expects(:geocode).with(@ip_address, {}).returns(@failure)
     assert_equal @failure, Geokit::Geocoders::MultiGeocoder.geocode(@ip_address)
   end
   

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: geokit
 version: !ruby/object:Gem::Version 
-  version: 1.3.2
+  version: 1.4.0
 platform: ruby
 authors: 
 - Andre Lewis
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-05-27 00:00:00 -07:00
+date: 2009-06-08 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency