geokit 1.6.5 → 1.6.6

data/lib/geokit/inflectors.rb

@@ -0,0 +1,38 @@
+module Geokit
+  module Inflector
+    require 'cgi'
+
+    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)
+      CGI.escape(s)
+    end
+
+    def camelize(str)
+      str.split('_').map {|w| w.capitalize}.join
+    end
+  end
+end

data/lib/geokit/mappable.rb

@@ -41,12 +41,18 @@ module Geokit
         formula = options[:formula] || Geokit::default_formula
         case formula
         when :sphere
+          error_classes = [Errno::EDOM]
+
+          # Ruby 1.9 raises {Math::DomainError}, but it is not defined in Ruby
+          # 1.8. Backwards-compatibly rescue both errors.
+          error_classes << Math::DomainError if defined?(Math::DomainError)
+
           begin
             units_sphere_multiplier(units) *
                 Math.acos( Math.sin(deg2rad(from.lat)) * Math.sin(deg2rad(to.lat)) +
                 Math.cos(deg2rad(from.lat)) * Math.cos(deg2rad(to.lat)) *
                 Math.cos(deg2rad(to.lng) - deg2rad(from.lng)))
-          rescue Errno::EDOM
+          rescue *error_classes
             0.0
           end
         when :flat
@@ -351,7 +357,7 @@ module Geokit
     # 100 Spear St, San Francisco, CA, 94101, US
     # Street number and street name are extracted from the street address attribute if they don't exist
     attr_accessor :street_number, :street_name, :street_address, :city, :state, :zip, :country_code, :country
-    attr_accessor :full_address, :all, :district, :province, :sub_premise
+    attr_accessor :full_address, :all, :district, :province, :sub_premise, :neighborhood
     # 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.
@@ -443,7 +449,13 @@ module Geokit
     end
 
     def to_yaml_properties
-      (instance_variables - ['@all']).sort
+      (instance_variables - ['@all', :@all]).sort
+    end
+
+    def encode_with(coder)
+      to_yaml_properties.each do |name|
+        coder[name[1..-1].to_s] = instance_variable_get(name.to_s)
+      end
     end
 
     # Returns a string representation of the instance.
@@ -545,4 +557,50 @@ module Geokit
       end
     end
   end
+  
+  # A complex polygon made of multiple points.  End point must equal start point to close the poly.
+  class Polygon
+    
+    attr_accessor :poly_y, :poly_x
+    
+    def initialize(points)
+      # Pass in an array of Geokit::LatLng
+      @poly_x = []
+      @poly_y = []
+
+      points.each do |point|
+        @poly_x << point.lng
+        @poly_y << point.lat
+      end
+      
+      # A Polygon must be 'closed', the last point equal to the first point
+      if not @poly_x[0] == @poly_x[-1] or not @poly_y[0] == @poly_y[-1]
+        # Append the first point to the array to close the polygon
+        @poly_x << @poly_x[0]
+        @poly_y << @poly_y[0]
+      end
+      
+    end
+
+    def contains?(point)
+      j = @poly_x.length - 1
+      oddNodes = false
+      x = point.lng
+      y = point.lat
+
+      for i in (0..j)
+        if (@poly_y[i] < y && @poly_y[j] >= y ||
+            @poly_y[j] < y && @poly_y[i] >= y)
+          if (@poly_x[i] + (y - @poly_y[i]) / (@poly_y[j] - @poly_y[i]) * (@poly_x[j] - @poly_x[i]) < x)
+            oddNodes = !oddNodes
+          end
+        end
+ 
+        j=i
+      end
+
+      oddNodes
+    end # contains?
+  end # class Polygon
+  
 end

data/lib/geokit/multi_geocoder.rb

@@ -0,0 +1,61 @@
+module Geokit
+  module Geocoders
+    # -------------------------------------------------------------------------------------------
+    # 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, 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, options
+            return res if res.success?
+          rescue => e
+            logger.error("An error has occurred during geocoding: #{e}\nAddress: #{address}. Provider: #{provider}")
+          end
+        end
+        # 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 => e
+            logger.error("An error has occurred during geocoding: #{e}\nLatlng: #{latlng}. Provider: #{provider}")
+          end
+        end
+        # If we get here, we failed completely.
+        GeoLoc.new
+      end
+    end
+  end
+end
+

data/lib/geokit/services/ca_geocoder.rb

@@ -0,0 +1,55 @@
+
+# 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>
+module Geokit
+ module Geocoders
+   class CaGeocoder < Geocoder
+
+     private
+
+     # Template method which does the geocode lookup.
+     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)
+       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
+ end
+end

data/lib/geokit/services/fcc.rb

@@ -0,0 +1,57 @@
+module Geokit
+  module Geocoders
+    class FCCGeocoder < 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://data.fcc.gov/api/block/find?format=json&latitude=#{Geokit::Inflector::url_escape(latlng.lat.to_s)}&longitude=#{Geokit::Inflector::url_escape(latlng.lng.to_s)}")
+        return GeoLoc.new unless (res.is_a?(Net::HTTPSuccess) || res.is_a?(Net::HTTPOK))
+        json = res.body
+        logger.debug "FCC reverse-geocoding. LL: #{latlng}. Result: #{json}"
+        return self.json2GeoLoc(json)
+      end
+
+      # Template method which does the geocode lookup.
+      #
+      # ==== EXAMPLES
+      # ll=GeoKit::LatLng.new(40, -85)
+      # Geokit::Geocoders::FCCGeocoder.geocode(ll) #
+
+      # JSON result looks like this
+      # => {"County"=>{"name"=>"Wayne", "FIPS"=>"18177"},
+      # "Block"=>{"FIPS"=>"181770103002004"},
+      # "executionTime"=>"0.099",
+      # "State"=>{"name"=>"Indiana", "code"=>"IN", "FIPS"=>"18"},
+      # "status"=>"OK"}
+
+      def self.json2GeoLoc(json, address="")
+        ret = nil
+        results = MultiJson.load(json)
+
+        if results.has_key?('Err') and results['Err']["msg"] == 'There are no results for this location'
+          return GeoLoc.new
+        end
+        # this should probably be smarter.
+        if !results['status'] == 'OK'
+          raise Geokit::Geocoders::GeocodeError
+        end
+
+        res = GeoLoc.new
+        res.provider      = 'fcc'
+        res.success       = true
+        res.precision     = 'block'
+        res.country_code  = 'US'
+        res.district      = results['County']['name']
+        res.district_fips = results['County']['FIPS']
+        res.state         = results['State']['code']
+        res.state_fips    = results['State']['FIPS']
+        res.block_fips    = results['Block']['FIPS']
+
+        res
+      end
+    end
+
+  end
+end

data/lib/geokit/services/geo_plugin.rb

@@ -0,0 +1,31 @@
+module Geokit
+  module Geocoders
+    # Provides geocoding based upon an IP address.  The underlying web service is geoplugin.net
+    class GeoPluginGeocoder < Geocoder
+      private
+
+      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
+      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
+
+  end
+end

data/lib/geokit/services/geonames.rb

@@ -0,0 +1,53 @@
+module Geokit
+  module Geocoders
+    # Another geocoding web service
+    # http://www.geonames.org
+    class GeonamesGeocoder < Geocoder
+
+      private
+
+      # Template method which does the geocode lookup.
+      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!(/,/, " ")
+        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
+  end
+end

data/lib/geokit/services/google.rb

@@ -0,0 +1,158 @@
+module Geokit
+  module Geocoders
+    # -------------------------------------------------------------------------------------------
+    # 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 = self.transcode_to_utf8(res.body)
+        logger.debug "Google reverse-geocoding. LL: #{latlng}. Result: #{xml}"
+        return self.xml2GeoLoc(xml)
+      end
+
+      # Template method which does the geocode lookup.
+      #
+      # 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#{bias_str}&key=#{Geokit::Geocoders::google}&oe=utf-8")
+        return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
+        xml = self.transcode_to_utf8(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=#{precise_ll(bias.center)}&spn=#{precise_ll(bias.to_span)}"
+        end
+      end
+
+      # Precision to 6 decimal places as per:
+      # https://developers.google.com/maps/documentation/staticmaps/?hl=en#Latlons
+      def self.precise_ll(loc)
+        "#{"%.6f" % loc.lat},#{"%.6f" % loc.lng}"
+      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
+        elsif doc.elements['//kml/Response/Status/code'].text == '620'
+          raise Geokit::TooManyQueriesError
+        else
+          logger.info "Google was unable to geocode address: "+address
+          return GeoLoc.new
+        end
+
+      rescue Geokit::TooManyQueriesError
+        # re-raise because of other rescue
+        raise Geokit::TooManyQueriesError, "Google returned a 620 status, too many queries. The given key has gone over the requests limit in the 24 hour period or has submitted too many requests in too short a period of time. If you're sending multiple requests in parallel or in a tight loop, use a timer or pause in your code to make sure you don't send the requests too quickly."
+      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.province = doc.elements['.//SubAdministrativeAreaName'].text if doc.elements['.//SubAdministrativeAreaName']
+        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']
+        res.country = doc.elements['.//CountryName'].text if doc.elements['.//CountryName']
+        res.district = doc.elements['.//DependentLocalityName'].text if doc.elements['.//DependentLocalityName']
+        # 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]
+
+        # 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
+      end
+      
+      def self.transcode_to_utf8(body)
+        require 'iconv' unless String.method_defined?(:encode)
+        if String.method_defined?(:encode)
+          body.encode!('UTF-8', 'UTF-8', :invalid => :replace)
+        else
+          ic = Iconv.new('UTF-8', 'UTF-8//IGNORE')
+          body = ic.iconv(body)
+        end        
+      end
+    end
+  end
+end