andre-geokit 1.2.3 → 1.2.4

data/README.markdown

@@ -3,7 +3,7 @@
 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 currently supports Google, Yahoo, Geocoder.us, and Geocoder.ca geocoders, and it provides a uniform response structure from all of them. 
+ * 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
@@ -45,7 +45,7 @@ See the RDOC more more ... there are also operations on rectangular bounds (e.g.
 
 ## CONFIGURATION
 
-If you're using this gem by itself, here's how to set configurations:
+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
@@ -110,7 +110,7 @@ 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.
+* 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.
@@ -119,6 +119,25 @@ creates a template with these settings and places it in `config/initializers/geo
 ### The Multigeocoder
 * Multi Geocoder - provides failover for the physical location geocoders.
 
+## 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

data/lib/geokit.rb

@@ -21,6 +21,8 @@ module Geokit
   end
 end
 
+path = File.expand_path(File.dirname(__FILE__))
+$: <<  path unless $:.include?(path)
 require 'geokit/geocoders'
 require 'geokit/mappable'
 

data/lib/geokit/geocoders.rb

@@ -220,7 +220,6 @@ module Geokit
       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.
@@ -397,30 +396,21 @@ module Geokit
         doc=REXML::Document.new(xml)
 
         if doc.elements['//kml/Response/Status/code'].text == '200'
-          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
-          # old way -- address_details=doc.elements['//AddressDetails','urn:oasis:names:tc:ciq:xsdschema:xAL:2.0']
-          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}[accuracy]
-          res.success=true
-          
-          return res
+          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 nill, 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
@@ -430,6 +420,33 @@ module Geokit
           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"]']
+        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.success=true
+        
+        return res        
+      end
     end
 
 
@@ -475,6 +492,7 @@ module Geokit
       # 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)
@@ -505,7 +523,7 @@ module Geokit
         res
       end
     end
-
+    
     # -------------------------------------------------------------------------------------------
     # The Multi Geocoder
     # -------------------------------------------------------------------------------------------    

data/lib/geokit/mappable.rb

@@ -1,3 +1,4 @@
+#require 'forwardable'
 
 module Geokit     
   # Contains class and instance methods providing distance calcuation services.  This
@@ -285,15 +286,31 @@ module Geokit
     
   end
 
-  # This class encapsulates the result of a geocoding call
+  # This class encapsulates the result of a geocoding call.
   # It's primary purpose is to homogenize the results of multiple
   # geocoding providers. It also provides some additional functionality, such as 
   # the "full address" method for geocoders that do not provide a 
   # full address in their results (for example, Yahoo), and the "is_us" method.
+  #
+  # Some geocoders can return multple results. Geoloc can capture multiple results through
+  # its "all" method. 
+  #
+  # For the geocoder setting the results, it would look something like this:
+  #     geo=GeoLoc.new(first_result)
+  #     geo.all.push(second_result)
+  #     geo.all.push(third_result)
+  #
+  # Then, for the user of the result:
+  #
+  #     puts geo.full_address     # just like usual
+  #     puts geo.all.size  => 3   # there's three results total
+  #     puts geo.all.first        # all is just an array or additional geolocs, 
+  #                                 so do what you want with it
   class GeoLoc < LatLng
+
     # Location attributes.  Full address is a concatenation of all values.  For example:
     # 100 Spear St, San Francisco, CA, 94101, US
-    attr_accessor :street_address, :city, :state, :zip, :country_code, :full_address
+    attr_accessor :street_address, :city, :state, :zip, :country_code, :full_address, :all
     # 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.
@@ -303,6 +320,8 @@ module Geokit
 
     # Constructor expects a hash of symbols to correspond with attributes.
     def initialize(h={})
+      @all = [self]
+      
       @street_address=h[:street_address] 
       @city=h[:city] 
       @state=h[:state] 
@@ -362,6 +381,10 @@ module Geokit
       a.delete_if { |e| !e || e == '' }
       a.join(', ')      
     end
+    
+    def to_yaml_properties
+      (instance_variables - ['@results']).sort
+    end
 
     # Returns a string representation of the instance.
     def to_s

data/test/test_geoloc.rb

@@ -46,4 +46,9 @@ class GeoLocTest < Test::Unit::TestCase #:nodoc: all
     @another = Geokit::GeoLoc.new @loc.to_hash    
     assert_equal @loc, @another
   end
+  
+  def test_all
+    assert_equal [@loc], @loc.all
+  end
+  
 end

data/test/test_google_geocoder.rb

@@ -12,6 +12,8 @@ class GoogleGeocoderTest < BaseGeocoderTest #:nodoc: all
   <?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>
   EOF
   
+  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"
+  
   def setup
     super
     @google_full_hash = {:street_address=>"100 Spear St", :city=>"San Francisco", :state=>"CA", :zip=>"94105", :country_code=>"US"}
@@ -85,4 +87,30 @@ class GoogleGeocoderTest < BaseGeocoderTest #:nodoc: all
     Geokit::Geocoders::GoogleGeocoder.expects(:call_geocoder_service).with(url).returns(response)
     assert !Geokit::Geocoders::GoogleGeocoder.geocode(@google_city_loc).success
   end 
-end
+  
+  def test_multiple_results
+    #Geokit::Geocoders::GoogleGeocoder.do_geocode('via Sandro Pertini 8, Ossona, MI')
+    response = MockSuccess.new
+    response.expects(:body).returns(GOOGLE_MULTI)
+    url = "http://maps.google.com/maps/geo?q=#{Geokit::Inflector.url_escape('via Sandro Pertini 8, Ossona, MI')}&output=xml&key=Google&oe=utf-8"
+    Geokit::Geocoders::GoogleGeocoder.expects(:call_geocoder_service).with(url).returns(response)
+    res=Geokit::Geocoders::GoogleGeocoder.geocode('via Sandro Pertini 8, Ossona, MI')
+    assert_equal "Lombardy", res.state
+    assert_equal "Mesero", res.city
+    assert_equal "45.4966243,8.8527131", res.ll
+    assert !res.is_us?
+    assert_equal "Via Sandro Pertini, 8, 20010 Mesero MI, Italy", res.full_address
+    assert_equal "8 Via Sandro Pertini", res.street_address
+    assert_equal "google", res.provider
+
+    assert_equal 2, res.all.size
+    res = res.all[1]
+    assert_equal "Lombardy", res.state
+    assert_equal "Ossona", res.city
+    assert_equal "45.5074444,8.90232", res.ll
+    assert !res.is_us?
+    assert_equal "Via Sandro Pertini, 20010 Ossona MI, Italy", res.full_address
+    assert_equal "Via Sandro Pertini", res.street_address
+    assert_equal "google", res.provider
+  end
+end

data/test/test_us_geocoder.rb

@@ -35,6 +35,15 @@ class UsGeocoderTest < BaseGeocoderTest #:nodoc: all
     assert !Geokit::Geocoders::UsGeocoder.geocode(@us_full_loc).success   
   end  
   
+  def test_all_method
+    response = MockSuccess.new
+    response.expects(:body).returns(GEOCODER_US_FULL)
+    url = "http://geocoder.us/service/csv/geocode?address=#{Geokit::Inflector.url_escape(@address)}"
+    Geokit::Geocoders::UsGeocoder.expects(:call_geocoder_service).with(url).returns(response)
+    res=Geokit::Geocoders::UsGeocoder.geocode(@address)
+    assert_equal 1, res.all.size
+  end
+  
   private
   
   def verify(location)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: andre-geokit
 version: !ruby/object:Gem::Version 
-  version: 1.2.3
+  version: 1.2.4
 platform: ruby
 authors: 
 - Andre Lewis and Bill Eisenhauer