abuiles-geokit 1.6.1

data/lib/geokit.rb

@@ -0,0 +1,55 @@
+module Geokit
+  VERSION = '1.5.0'
+
+  # These defaults are used in Geokit::Mappable.distance_to and in acts_as_mappable
+  @@default_units = :miles
+  @@default_formula = :sphere
+
+  [:default_units, :default_formula].each do |sym|
+    class_eval <<-EOS, __FILE__, __LINE__
+      def self.#{sym}
+        if defined?(#{sym.to_s.upcase})
+          #{sym.to_s.upcase}
+        else
+          @@#{sym}
+        end
+      end
+
+      def self.#{sym}=(obj)
+        @@#{sym} = obj
+      end
+    EOS
+  end
+end
+
+require 'net/http'
+require 'ipaddr'
+require 'rexml/document'
+require 'yaml'
+require 'timeout'
+require 'logger'
+require 'active_support/core_ext/hash'
+require 'active_support/core_ext/object/conversions'
+require 'openssl'
+require 'base64'
+require 'json'
+
+require 'geokit/too_many_queries_error'
+require 'geokit/inflector'
+require 'geokit/geocoders'
+require 'geokit/mappable'
+require 'geokit/lat_lng'
+require 'geokit/geo_loc'
+require 'geokit/bounds'
+require 'geokit/geocoders/geocode_error'
+require 'geokit/geocoders/geocoder'
+
+require 'geokit/geocoders/ca_geocoder'
+require 'geokit/geocoders/geo_plugin_geocoder'
+require 'geokit/geocoders/geonames_geocoder'
+require 'geokit/geocoders/google_geocoder'
+require 'geokit/geocoders/google_premier_geocoder'
+require 'geokit/geocoders/ip_geocoder'
+require 'geokit/geocoders/multi_geocoder'
+require 'geokit/geocoders/us_geocoder'
+require 'geokit/geocoders/yahoo_geocoder'

data/lib/geokit/bounds.rb

@@ -0,0 +1,95 @@
+module Geokit
+  # Bounds represents a rectangular bounds, defined by the SW and NE corners
+  class Bounds
+    # sw and ne are LatLng objects
+    attr_accessor :sw, :ne
+
+    # provide sw and ne to instantiate a new Bounds instance
+    def initialize(sw,ne)
+      raise ArgumentError if !(sw.is_a?(Geokit::LatLng) && ne.is_a?(Geokit::LatLng))
+      @sw,@ne=sw,ne
+    end
+
+    #returns the a single point which is the center of the rectangular bounds
+    def center
+      @sw.midpoint_to(@ne)
+    end
+
+    # a simple string representation:sw,ne
+    def to_s
+      "#{@sw.to_s},#{@ne.to_s}"
+    end
+
+    # a two-element array of two-element arrays: sw,ne
+    def to_a
+      [@sw.to_a, @ne.to_a]
+    end
+
+    # Returns true if the bounds contain the passed point.
+    # allows for bounds which cross the meridian
+    def contains?(point)
+      point=Geokit::LatLng.normalize(point)
+      res = point.lat > @sw.lat && point.lat < @ne.lat
+      if crosses_meridian?
+        res &= point.lng < @ne.lng || point.lng > @sw.lng
+      else
+        res &= point.lng < @ne.lng && point.lng > @sw.lng
+      end
+      res
+    end
+
+    # returns true if the bounds crosses the international dateline
+    def crosses_meridian?
+      @sw.lng > @ne.lng
+    end
+
+    # Returns true if the candidate object is logically equal.  Logical equivalence
+    # is true if the lat and lng attributes are the same for both objects.
+    def ==(other)
+      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
+      def from_point_and_radius(point,radius,options={})
+        point=LatLng.normalize(point)
+        p0=point.endpoint(0,radius,options)
+        p90=point.endpoint(90,radius,options)
+        p180=point.endpoint(180,radius,options)
+        p270=point.endpoint(270,radius,options)
+        sw=Geokit::LatLng.new(p180.lat,p270.lng)
+        ne=Geokit::LatLng.new(p0.lat,p90.lng)
+        Geokit::Bounds.new(sw,ne)
+      end
+
+      # Takes two main combinations of arguments to create a bounds:
+      # point,point   (this is the only one which takes two arguments
+      # [point,point]
+      # . . . where a point is anything LatLng#normalize can handle (which is quite a lot)
+      #
+      # NOTE: everything combination is assumed to pass points in the order sw, ne
+      def normalize (thing,other=nil)
+        # maybe this will be simple -- an actual bounds object is passed, and we can all go home
+        return thing if thing.is_a? Bounds
+
+        # no? OK, if there's no "other," the thing better be a two-element array
+        thing,other=thing if !other && thing.is_a?(Array) && thing.size==2
+
+        # Now that we're set with a thing and another thing, let LatLng do the heavy lifting.
+        # Exceptions may be thrown
+        Bounds.new(Geokit::LatLng.normalize(thing),Geokit::LatLng.normalize(other))
+      end
+    end
+  end
+end

data/lib/geokit/geo_loc.rb

@@ -0,0 +1,115 @@
+module Geokit
+  # 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, :country, :full_address, :all, :district, :province
+    # 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, :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
+    # precision. see http://code.google.com/apis/maps/documentation/geocoding/#GeocodingAccuracy
+    attr_accessor :accuracy
+
+    # Constructor expects a hash of symbols to correspond with attributes.
+    def initialize(h={})
+      @all = [self]
+
+      @street_address=h[:street_address]
+      @city=h[:city]
+      @state=h[:state]
+      @zip=h[:zip]
+      @country_code=h[:country_code]
+      @province = h[:province]
+      @success=false
+      @precision='unknown'
+      @full_address=nil
+      super(h[:lat],h[:lng])
+    end
+
+    # Returns true if geocoded to the United States.
+    def is_us?
+      country_code == 'US'
+    end
+
+    def success?
+      success == true
+    end
+
+    # full_address is provided by google but not by yahoo. It is intended that the google
+    # geocoding method will provide the full address, whereas for yahoo it will be derived
+    # from the parts of the address we do have.
+    def full_address
+      @full_address ? @full_address : to_geocodeable_s
+    end
+
+    # Extracts the street number from the street address if the street address
+    # has a value.
+    def street_number
+      street_address[/(\d*)/] if street_address
+    end
+
+    # Returns the street name portion of the street address.
+    def street_name
+       street_address[street_number.length, street_address.length].strip if street_address
+    end
+
+    # gives you all the important fields as key-value pairs
+    def hash
+      res={}
+      [:success,:lat,:lng,:country_code,:city,:state,:zip,:street_address,:province,:district,:provider,:full_address,:is_us?,:ll,:precision].each { |s| res[s] = self.send(s.to_s) }
+      res
+    end
+    alias to_hash hash
+
+    # Sets the city after capitalizing each word within the city name.
+    def city=(city)
+      @city = Geokit::Inflector::titleize(city) if city
+    end
+
+    # 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
+
+    # 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
+      a=[street_address, district, city, province, state, zip, country_code].compact
+      a.delete_if { |e| !e || e == '' }
+      a.join(', ')
+    end
+
+    def to_yaml_properties
+      (instance_variables - ['@all']).sort
+    end
+
+    # Returns a string representation of the instance.
+    def to_s
+      "Provider: #{provider}\nStreet: #{street_address}\nCity: #{city}\nState: #{state}\nZip: #{zip}\nLatitude: #{lat}\nLongitude: #{lng}\nCountry: #{country_code}\nSuccess: #{success}"
+    end
+  end
+end

data/lib/geokit/geocoders.rb

@@ -0,0 +1,68 @@
+module Geokit
+  # Contains a range of geocoders:
+  #
+  # ### "regular" address geocoders
+  # * Yahoo Geocoder - requires an API key.
+  # * Geocoder.us - may require authentication if performing more than the free request limit.
+  # * Geocoder.ca - for Canada; may require authentication as well.
+  # * Geonames - a free geocoder
+  #
+  # ### address geocoders that also provide reverse geocoding
+  # * Google Geocoder - requires an API key.
+  #
+  # ### IP address geocoders
+  # * IP Geocoder - geocodes an IP address using hostip.info's web service.
+  # * Geoplugin.net -- another IP address geocoder
+  #
+  # ### The Multigeocoder
+  # * Multi Geocoder - provides failover for the physical location geocoders.
+  #
+  # Some of these geocoders require configuration. You don't have to provide it here. See the README.
+  module Geocoders
+    @@proxy_addr = nil
+    @@proxy_port = nil
+    @@proxy_user = nil
+    @@proxy_pass = nil
+    @@request_timeout = nil
+    @@yahoo = 'REPLACE_WITH_YOUR_YAHOO_KEY'
+    @@google = 'REPLACE_WITH_YOUR_GOOGLE_KEY'
+    @@google_client = 'REPLACE_WITH_YOUR_GOOGLE_CLIENT'
+    @@google_channel = 'REPLACE_WITH_YOUR_GOOGLE_CHANNEL'
+    @@geocoder_us = false
+    @@geocoder_ca = false
+    @@geonames = false
+    @@provider_order = [:google,:us]
+    @@ip_provider_order = [:geo_plugin,:ip]
+    @@logger=Logger.new(STDOUT)
+    @@logger.level=Logger::INFO
+    @@domain = nil
+
+    def self.__define_accessors
+      class_variables.each do |v|
+        sym = v.to_s.delete("@").to_sym
+        unless self.respond_to? sym
+          module_eval <<-EOS, __FILE__, __LINE__
+            def self.#{sym}
+              value = if defined?(#{sym.to_s.upcase})
+                #{sym.to_s.upcase}
+              else
+                @@#{sym}
+              end
+              if value.is_a?(Hash)
+                value = (self.domain.nil? ? nil : value[self.domain]) || value.values.first
+              end
+              value
+            end
+
+            def self.#{sym}=(obj)
+              @@#{sym} = obj
+            end
+          EOS
+        end
+      end
+    end
+
+    __define_accessors
+
+  end
+end

data/lib/geokit/geocoders/ca_geocoder.rb

@@ -0,0 +1,54 @@
+module Geokit
+  module Geocoders
+    # 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>
+    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/geocoders/geo_plugin_geocoder.rb

@@ -0,0 +1,30 @@
+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/geocoders/geocode_error.rb

@@ -0,0 +1,7 @@
+module Geokit
+  module Geocoders
+    # Error which is thrown in the event a geocoding error occurs.
+    class GeocodeError < StandardError
+    end
+  end
+end

data/lib/geokit/geocoders/geocoder.rb

@@ -0,0 +1,75 @@
+module Geokit
+  module Geocoders
+
+
+    # -------------------------------------------------------------------------------------------
+    # Geocoder Base class -- every geocoder should inherit from this
+    # -------------------------------------------------------------------------------------------
+
+    # The Geocoder base class which defines the interface to be used by all
+    # other geocoders.
+    class Geocoder
+      # 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, 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
+      # are responsible for implementing.  Returns a populated GeoLoc or an
+      # empty one with a failed success code.
+      def self.reverse_geocode(latlng)
+        res = do_reverse_geocode(latlng)
+        return res.success? ? res : GeoLoc.new
+      end
+
+      # Call the geocoder service using the timeout if configured.
+      def self.call_geocoder_service(url)
+        Timeout::timeout(Geokit::Geocoders::request_timeout) { return self.do_get(url) } if Geokit::Geocoders::request_timeout
+        return self.do_get(url)
+      rescue TimeoutError
+        return nil
+      end
+
+      # Not all geocoders can do reverse geocoding. So, unless the subclass explicitly overrides this method,
+      # a call to reverse_geocode will return an empty GeoLoc. If you happen to be using MultiGeocoder,
+      # this will cause it to failover to the next geocoder, which will hopefully be one which supports reverse geocoding.
+      def self.do_reverse_geocode(latlng)
+        return GeoLoc.new
+      end
+
+      protected
+
+      def self.logger()
+        Geokit::Geocoders::logger
+      end
+
+      private
+
+      # Wraps the geocoder call around a proxy if necessary.
+      def self.do_get(url)
+        uri = URI.parse(url)
+        req = Net::HTTP::Get.new(url)
+        req.basic_auth(uri.user, uri.password) if uri.userinfo
+        res = Net::HTTP::Proxy(Geokit::Geocoders::proxy_addr,
+                Geokit::Geocoders::proxy_port,
+                Geokit::Geocoders::proxy_user,
+                Geokit::Geocoders::proxy_pass).start(uri.host, uri.port) { |http| http.get(uri.path + "?" + uri.query) }
+        return res
+      end
+
+      # Adds subclass' geocode method making it conveniently available through
+      # the base class.
+      def self.inherited(clazz)
+        class_name = clazz.name.split('::').last
+        src = <<-END_SRC
+          def self.#{Geokit::Inflector.underscore(class_name)}(address, options = {})
+            #{class_name}.geocode(address, options)
+          end
+        END_SRC
+        class_eval(src)
+      end
+    end
+  end
+end