abuiles-geokit 1.6.1

data/lib/geokit/geocoders/geonames_geocoder.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/geocoders/google_geocoder.rb

@@ -0,0 +1,145 @@
+module Geokit
+  module Geocoders
+    # 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
+
+      ENDPOINT = "http://maps.google.com/maps/geo"
+
+      private
+
+        # Template method which does the reverse-geocode lookup.
+        def self.do_reverse_geocode(latlng)
+          latlng = LatLng.normalize(latlng)
+          params = { :ll => latlng.ll, :output => "xml", :key => Geokit::Geocoders::google, :oe => "utf-8" }
+          url = "#{ENDPOINT}?" + params.to_query
+          res = self.call_geocoder_service(url)
+          return GeoLoc.new unless (res.is_a?(Net::HTTPSuccess) || res.is_a?(Net::HTTPOK))
+          xml = res.body
+          logger.debug "Google reverse-geocoding. LL: #{latlng}. Result: #{xml}"
+          return self.xml2GeoLoc(xml)
+        end
+
+        # Template method which does the geocode lookup.
+        #
+        # 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 = {})
+          address_str = address.is_a?(GeoLoc) ? address.to_geocodeable_s : address
+          params = { :q => address_str, :output => "xml", :key => Geokit::Geocoders::google, :oe => "utf-8" }.merge(bias_options(options[:bias]))
+          url = "#{ENDPOINT}?" + params.to_query
+          res = self.call_geocoder_service(url)
+          return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
+          xml = res.body.force_encoding('utf-8')
+          logger.debug "Google geocoding. Address: #{address}. Result: #{xml}"
+          return self.xml2GeoLoc(xml, address)
+        end
+
+        def self.bias_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 }
+          else
+            {}
+          end
+        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
+
+    end
+  end
+end

data/lib/geokit/geocoders/google_premier_geocoder.rb

@@ -0,0 +1,147 @@
+module Geokit
+  module Geocoders
+    class GooglePremierGeocoder < Geocoder
+
+      HOST = "maps.googleapis.com"
+      ENDPOINT = "/maps/api/geocode/json"
+
+      protected
+
+        def self.do_reverse_geocode(latlng)
+          latlng = LatLng.normalize(latlng)
+          params = { :latlng => latlng.ll, :sensor => false }
+          signed_url = signed_url_for_params(params)
+          res = self.call_geocoder_service(signed_url)
+          return GeoLoc.new unless (res.is_a?(Net::HTTPSuccess) || res.is_a?(Net::HTTPOK))
+          json = JSON.parse(res.body)
+          logger.debug "Google reverse-geocoding. LL: #{latlng}. Result: #{json}"
+          return self.json_to_geo_loc(json)
+        end
+
+        def self.do_geocode(address, options = {})
+          address_str = address.is_a?(GeoLoc) ? address.to_geocodeable_s : address
+          params = { :address => address_str, :sensor => false }
+          signed_url = signed_url_for_params(params)
+          res = self.call_geocoder_service(signed_url)
+          return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
+          json = JSON.parse(res.body)
+          logger.debug "Google geocoding. Address: #{address}. Result: #{json}"
+          return self.json_to_geo_loc(json, address)
+        end
+
+        def self.json_to_geo_loc(json, address="")
+          if json["status"] == "OK"
+            geoloc = nil
+
+            # iterate through each and extract as a geoloc
+            json["results"].each do |result|
+              extracted_geoloc = extract_result(result) # 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 json["status"] == "ZERO_RESULTS"
+            return GeoLoc.new
+          elsif json["status"] == "OVER_QUERY_LIMIT"
+            raise Geokit::TooManyQueriesError
+          elsif json["status"] == "REQUEST_DENIED"
+            logger.error "Google Premier request denied: "+$!
+          elsif json["status"] == "INVALID_REQUEST"
+            logger.error "Google Premier invalid request: "+$!
+          else
+            logger.info "Google was unable to geocode address: "+address
+            return GeoLoc.new
+          end
+        rescue Geokit::TooManyQueriesError
+          raise Geokit::TooManyQueriesError, "Google Premier 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 Premier geocoding call: "+$!
+          return GeoLoc.new
+        end
+
+        ACCURACY_MAP = {
+          "ROOFTOP" => 8,
+          "RANGE_INTERPOLATED" => 7,
+          "GEOMETRIC_CENTER" => 6,
+          "APPROXIMATE" => 5,
+        }
+
+        # extracts a single geoloc from a result in the google results json
+        def self.extract_result(result)
+          res = GeoLoc.new
+
+          res.provider = "google_premier"
+
+          geometry = result["geometry"] if result
+
+          res.accuracy  = ACCURACY_MAP[geometry["location_type"]] if geometry
+          res.precision = geometry["location_type"].underscore if geometry
+
+          location = geometry["location"] if geometry
+          res.lat = location["lat"] if location
+          res.lng = location["lng"] if location
+
+          res.full_address = result["formatted_address"]
+          res.street_address = result["formatted_address"]
+
+          address_components = result["address_components"] if result
+          address_components.each do |component|
+            res.zip = component["long_name"] if component["types"].include?("postal_code")
+            res.country = component["long_name"] if component["types"].include?("country")
+            res.country_code = component["short_name"] if component["types"].include?("country")
+            res.city = component["long_name"] if component["types"].include?("locality")
+            res.state = component["long_name"] if component["types"].include?("administrative_area_level_1")
+            res.province = component["long_name"] if component["types"].include?("administrative_area_level_2")
+            res.district = component["long_name"] if component["types"].include?("administrative_area_level_3")
+          end if address_components
+
+          bounds = geometry["bounds"]
+
+          res.suggested_bounds = Bounds.normalize(
+            [bounds["southwest"]["lat"], bounds["southwest"]["lng"]],
+            [bounds["northeast"]["lat"], bounds["northeast"]["lng"]]
+          ) if bounds
+
+          res.success = true
+
+          res
+        end
+
+      private
+
+        def self.url_for_params(params)
+          params_to_sign = params
+          "http://" + HOST + string_to_sign
+        end
+
+        def self.signed_url_for_params(params)
+          params_to_sign = params.merge({ :client => Geokit::Geocoders.google_client, :channel => Geokit::Geocoders.google_channel }).reject{ |key, value| value.nil? }
+          string_to_sign = "#{ENDPOINT}?#{params_to_sign.to_query}"
+          signature = signature_for_string(string_to_sign)
+          "http://" + HOST + string_to_sign + "&signature=#{signature}"
+        end
+
+        def self.signature_for_string(string)
+          raw_private_key = url_safe_base64_decode(Geokit::Geocoders.google)
+          digest = OpenSSL::Digest::Digest.new("sha1")
+          raw_signature = OpenSSL::HMAC.digest(digest, raw_private_key, string)
+          url_safe_base64_encode(raw_signature)
+        end
+
+        def self.url_safe_base64_decode(base64_string)
+          Base64.decode64(base64_string.tr("-_","+/"))
+        end
+
+        def self.url_safe_base64_encode(raw)
+          Base64.encode64(raw).tr("+/","-_").strip
+        end
+
+    end
+  end
+end

data/lib/geokit/geocoders/ip_geocoder.rb

@@ -0,0 +1,76 @@
+module Geokit
+  module Geocoders
+    # Provides geocoding based upon an IP address.  The underlying web service is a hostip.info
+    # which sources their data through a combination of publicly available information as well
+    # as community contributions.
+    class IpGeocoder < Geocoder
+
+      # A number of non-routable IP ranges.
+      #
+      # --
+      # Sources for these:
+      #   RFC 3330: Special-Use IPv4 Addresses
+      #   The bogon list: http://www.cymru.com/Documents/bogon-list.html
+
+      NON_ROUTABLE_IP_RANGES = [
+	IPAddr.new('0.0.0.0/8'),      # "This" Network
+	IPAddr.new('10.0.0.0/8'),     # Private-Use Networks
+	IPAddr.new('14.0.0.0/8'),     # Public-Data Networks
+	IPAddr.new('127.0.0.0/8'),    # Loopback
+	IPAddr.new('169.254.0.0/16'), # Link local
+	IPAddr.new('172.16.0.0/12'),  # Private-Use Networks
+	IPAddr.new('192.0.2.0/24'),   # Test-Net
+	IPAddr.new('192.168.0.0/16'), # Private-Use Networks
+	IPAddr.new('198.18.0.0/15'),  # Network Interconnect Device Benchmark Testing
+	IPAddr.new('224.0.0.0/4'),    # Multicast
+	IPAddr.new('240.0.0.0/4')     # Reserved for future use
+      ].freeze
+
+      private
+
+      # Given an IP address, returns a GeoLoc instance which contains latitude,
+      # longitude, city, and country code.  Sets the success attribute to false if the ip
+      # parameter does not match an ip address.
+      def self.do_geocode(ip, options = {})
+        return GeoLoc.new unless /^(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})?$/.match(ip)
+        return GeoLoc.new if self.private_ip_address?(ip)
+        url = "http://api.hostip.info/get_html.php?ip=#{ip}&position=true"
+        response = self.call_geocoder_service(url)
+        response.is_a?(Net::HTTPSuccess) ? parse_body(response.body) : GeoLoc.new
+      rescue
+        logger.error "Caught an error during HostIp geocoding call: "+$!
+        return GeoLoc.new
+      end
+
+      # Converts the body to YAML since its in the form of:
+      #
+      # Country: UNITED STATES (US)
+      # City: Sugar Grove, IL
+      # Latitude: 41.7696
+      # Longitude: -88.4588
+      #
+      # then instantiates a GeoLoc instance to populate with location data.
+      def self.parse_body(body) # :nodoc:
+        yaml = YAML.load(body)
+        res = GeoLoc.new
+        res.provider = 'hostip'
+        res.city, res.state = yaml['City'].split(', ')
+        country, res.country_code = yaml['Country'].split(' (')
+        res.lat = yaml['Latitude']
+        res.lng = yaml['Longitude']
+        res.country_code.chop!
+        res.success = !(res.city =~ /\(.+\)/)
+        res
+      end
+
+      # Checks whether the IP address belongs to a private address range.
+      #
+      # This function is used to reduce the number of useless queries made to
+      # the geocoding service. Such queries can occur frequently during
+      # integration tests.
+      def self.private_ip_address?(ip)
+	return NON_ROUTABLE_IP_RANGES.any? { |range| range.include?(ip) }
+      end
+    end
+  end
+end

data/lib/geokit/geocoders/multi_geocoder.rb

@@ -0,0 +1,60 @@
+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
+            logger.error("Something has gone very wrong during geocoding, OR you have configured an invalid class name in Geokit::Geocoders::provider_order. Address: #{address}. Provider: #{provider}")
+          end
+        end
+        # If we get here, we failed completely.
+        GeoLoc.new
+      end
+
+      # 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