collectiveidea-graticule 0.2.12

data/init.rb

@@ -0,0 +1,2 @@
+
+require 'graticule'

data/lib/graticule.rb

@@ -0,0 +1,26 @@
+$:.unshift(File.dirname(__FILE__))
+
+require 'active_support'
+
+require 'graticule/version'
+require 'graticule/core_ext'
+require 'graticule/location'
+require 'graticule/geocoder'
+require 'graticule/geocoder/base'
+require 'graticule/geocoder/bogus'
+require 'graticule/geocoder/rest'
+require 'graticule/geocoder/google'
+require 'graticule/geocoder/host_ip'
+require 'graticule/geocoder/multi'
+require 'graticule/geocoder/yahoo'
+require 'graticule/geocoder/geocoder_ca'
+require 'graticule/geocoder/geocoder_us'
+require 'graticule/geocoder/local_search_maps'
+require 'graticule/geocoder/meta_carta'
+require 'graticule/geocoder/postcode_anywhere'
+require 'graticule/geocoder/multimap'
+require 'graticule/geocoder/mapquest'
+require 'graticule/distance'
+require 'graticule/distance/haversine'
+require 'graticule/distance/spherical'
+require 'graticule/distance/vincenty'

data/lib/graticule/cli.rb

@@ -0,0 +1,64 @@
+require 'graticule'
+require 'optparse'
+
+module Graticule
+  
+  # A command line interface for geocoding.  From the command line, run:
+  #
+  #   geocode 49423 
+  #
+  # Outputs:
+  #
+  #   # Holland, MI 49423 US
+  #   # latitude: 42.7654, longitude: -86.1085
+  #
+  # == Usage: geocode [options] location
+  # 
+  # Options: 
+  #     -s, --service service            Geocoding service
+  #     -a, --apikey apikey              API key for the selected service
+  #     -h, --help                       Help
+  class Cli
+    
+    def self.start(args, out = STDOUT)
+      options = { :service => :yahoo, :api_key => 'YahooDemo' }
+      
+      OptionParser.new do |opts|
+        opts.banner = "Usage: geocode [options] location"
+        opts.separator ""
+        opts.separator "Options: "
+
+        opts.on("-s service", %w(yahoo google geocoder_us metacarta), "--service service", "Geocoding service") do |service|
+          options[:service] = service
+        end
+        
+        opts.on("-a apikey", "--apikey apikey", "API key for the selected service")
+        
+        opts.on_tail("-h", "--help", "Help") do
+          puts opts
+          exit
+        end
+      end.parse! args
+
+      options[:location] = args.join(" ")
+      
+      result = Graticule.service(options[:service]).new(*options[:api_key].split(',')).locate(options[:location])
+      location = (result.is_a?(Array) ? result.first : result)
+      if location
+        out << location.to_s(:coordinates => true)
+        exit 0
+      else
+        out << "Location not found"
+        exit 1
+      end
+    rescue Graticule::CredentialsError
+      $stderr.puts "Invalid API key. Pass your #{options[:service]} API key using the -a option. "
+    rescue OptionParser::InvalidArgument, OptionParser::InvalidOption,
+        Graticule::Error => error
+      $stderr.puts error.message
+    end
+    
+    
+  end
+end
+

data/lib/graticule/core_ext.rb

@@ -0,0 +1,15 @@
+module Graticule
+  module RadiansAndDegrees
+    # Convert from degrees to radians
+    def to_radians
+      ( self / 360.0 ) * Math::PI * 2
+    end
+  
+    # Convert from radians to degrees
+    def to_degrees
+      ( self * 360.0 ) / Math::PI / 2
+    end
+  end
+end
+
+Numeric.send :include, Graticule::RadiansAndDegrees

data/lib/graticule/distance.rb

@@ -0,0 +1,18 @@
+module Graticule
+  module Distance
+    
+    EARTH_RADIUS = { :kilometers => 6378.135, :miles => 3963.1676 }
+    # WGS-84 numbers
+    EARTH_MAJOR_AXIS_RADIUS = { :kilometers => 6378.137, :miles => 3963.19059 }
+    EARTH_MINOR_AXIS_RADIUS = { :kilometers => 6356.7523142, :miles => 3949.90276 }
+
+    class DistanceFormula
+      include Math
+      extend Math
+       
+      def initialize
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/graticule/distance/haversine.rb

@@ -0,0 +1,40 @@
+module Graticule
+  module Distance
+    #
+    # The Haversine Formula works better at small distances than the Spherical Law of Cosines
+    #
+    # Thanks to Chris Veness (http://www.movable-type.co.uk/scripts/LatLong.html)
+    # for distance formulas.
+    #
+    class Haversine < DistanceFormula
+      
+      # Calculate the distance between two Locations using the Haversine formula
+      #
+      #   Graticule::Distance::Haversine.distance(
+      #     Graticule::Location.new(:latitude => 42.7654, :longitude => -86.1085),
+      #     Graticule::Location.new(:latitude => 41.849838, :longitude => -87.648193)
+      #   )
+      #   #=> 101.061720831836
+      #
+      def self.distance(from, to, units = :miles)
+        from_longitude  = from.longitude.to_radians
+        from_latitude   = from.latitude.to_radians
+        to_longitude    = to.longitude.to_radians
+        to_latitude     = to.latitude.to_radians
+
+        latitude_delta  = to_latitude - from_latitude
+        longitude_delta = to_longitude - from_longitude
+
+        a = sin(latitude_delta/2)**2 + 
+            cos(from_latitude) * 
+            cos(to_latitude) * 
+            sin(longitude_delta/2)**2
+
+        c = 2 * atan2(sqrt(a), sqrt(1-a))
+
+        d = EARTH_RADIUS[units.to_sym] * c
+      end
+
+    end
+  end
+end

data/lib/graticule/distance/spherical.rb

@@ -0,0 +1,52 @@
+module Graticule
+  module Distance
+
+    #
+    # The Spherical Law of Cosines is the simplist though least accurate distance
+    # formula (earth isn't a perfect sphere).
+    #
+    class Spherical < DistanceFormula
+
+      # Calculate the distance between two Locations using the Spherical formula
+      #
+      #   Graticule::Distance::Spherical.distance(
+      #     Graticule::Location.new(:latitude => 42.7654, :longitude => -86.1085),
+      #     Graticule::Location.new(:latitude => 41.849838, :longitude => -87.648193)
+      #   )
+      #   #=> 101.061720831853
+      #
+      def self.distance(from, to, units = :miles)
+        from_longitude  = from.longitude.to_radians
+        from_latitude   = from.latitude.to_radians
+        to_longitude    = to.longitude.to_radians
+        to_latitude     = to.latitude.to_radians
+
+        Math.acos(
+            Math.sin(from_latitude) *
+            Math.sin(to_latitude) +
+
+            Math.cos(from_latitude) * 
+            Math.cos(to_latitude) *
+            Math.cos(to_longitude - from_longitude)
+        ) * EARTH_RADIUS[units.to_sym]
+      end
+
+      def self.to_sql(options)
+        options = {
+          :units => :miles,
+          :latitude_column => 'latitude',
+          :longitude_column => 'longitude'
+        }.merge(options)
+        %{(ACOS(
+            SIN(RADIANS(#{options[:latitude]})) *
+            SIN(RADIANS(#{options[:latitude_column]})) +
+            COS(RADIANS(#{options[:latitude]})) *
+            COS(RADIANS(#{options[:latitude_column]})) *
+            COS(RADIANS(#{options[:longitude_column]}) - RADIANS(#{options[:longitude]}))
+          ) * #{Graticule::Distance::EARTH_RADIUS[options[:units].to_sym]})
+        }.gsub("\n", '').squeeze(" ")
+      end
+  
+    end
+  end
+end

data/lib/graticule/distance/vincenty.rb

@@ -0,0 +1,76 @@
+module Graticule
+  module Distance
+
+    #
+    # The Vincenty Formula uses an ellipsoidal model of the earth, which is very accurate.
+    #
+    # Thanks to Chris Veness (http://www.movable-type.co.uk/scripts/LatLongVincenty.html)
+    # for distance formulas.
+    #
+    class Vincenty < DistanceFormula
+
+      # Calculate the distance between two Locations using the Vincenty formula
+      #
+      #   Graticule::Distance::Vincenty.distance(
+      #     Graticule::Location.new(:latitude => 42.7654, :longitude => -86.1085),
+      #     Graticule::Location.new(:latitude => 41.849838, :longitude => -87.648193)
+      #   )
+      #   #=> 101.070118000159
+      #
+      def self.distance(from, to, units = :miles)
+        from_longitude  = from.longitude.to_radians
+        from_latitude   = from.latitude.to_radians
+        to_longitude    = to.longitude.to_radians
+        to_latitude     = to.latitude.to_radians
+        
+        earth_major_axis_radius = EARTH_MAJOR_AXIS_RADIUS[units.to_sym]
+        earth_minor_axis_radius = EARTH_MINOR_AXIS_RADIUS[units.to_sym]
+
+        f = (earth_major_axis_radius - earth_minor_axis_radius) / earth_major_axis_radius
+
+        l = to_longitude - from_longitude
+        u1 = atan((1-f) * tan(from_latitude))
+        u2 = atan((1-f) * tan(to_latitude))
+        sin_u1 = sin(u1)
+        cos_u1 = cos(u1)
+        sin_u2 = sin(u2)
+        cos_u2 = cos(u2)
+
+        lambda = l
+        lambda_p = 2 * PI
+        iteration_limit = 20
+        while (lambda-lambda_p).abs > 1e-12 && (iteration_limit -= 1) > 0
+          sin_lambda = sin(lambda)
+          cos_lambda = cos(lambda)
+          sin_sigma = sqrt((cos_u2*sin_lambda) * (cos_u2*sin_lambda) + 
+            (cos_u1*sin_u2-sin_u1*cos_u2*cos_lambda) * (cos_u1*sin_u2-sin_u1*cos_u2*cos_lambda))
+          return 0 if sin_sigma == 0  # co-incident points
+          cos_sigma = sin_u1*sin_u2 + cos_u1*cos_u2*cos_lambda
+          sigma = atan2(sin_sigma, cos_sigma)
+          sin_alpha = cos_u1 * cos_u2 * sin_lambda / sin_sigma
+          cosSqAlpha = 1 - sin_alpha*sin_alpha
+          cos2SigmaM = cos_sigma - 2*sin_u1*sin_u2/cosSqAlpha
+
+          cos2SigmaM = 0 if cos2SigmaM.nan?  # equatorial line: cosSqAlpha=0 (§6)
+
+          c = f/16*cosSqAlpha*(4+f*(4-3*cosSqAlpha))
+          lambda_p = lambda
+          lambda = l + (1-c) * f * sin_alpha *
+            (sigma + c*sin_sigma*(cos2SigmaM+c*cos_sigma*(-1+2*cos2SigmaM*cos2SigmaM)))
+       end
+       # formula failed to converge (happens on antipodal points)
+       # We'll call Haversine formula instead.
+       return Haversine.distance(from, to, units) if iteration_limit == 0 
+
+       uSq = cosSqAlpha * (earth_major_axis_radius**2 - earth_minor_axis_radius**2) / (earth_minor_axis_radius**2)
+       a = 1 + uSq/16384*(4096+uSq*(-768+uSq*(320-175*uSq)))
+       b = uSq/1024 * (256+uSq*(-128+uSq*(74-47*uSq)))
+       delta_sigma = b*sin_sigma*(cos2SigmaM+b/4*(cos_sigma*(-1+2*cos2SigmaM*cos2SigmaM)-
+         b/6*cos2SigmaM*(-3+4*sin_sigma*sin_sigma)*(-3+4*cos2SigmaM*cos2SigmaM)))
+         
+        earth_minor_axis_radius * a * (sigma-delta_sigma)
+      end
+  
+    end
+  end
+end

data/lib/graticule/geocoder.rb

@@ -0,0 +1,21 @@
+
+module Graticule
+  
+  # Get a geocoder for the given service
+  #
+  #   geocoder = Graticule.service(:google).new "api_key"
+  #
+  # See the documentation for your specific geocoder for more information
+  #
+  def self.service(name)
+    Geocoder.const_get name.to_s.camelize
+  end
+  
+  # Base error class
+  class Error < RuntimeError; end
+  class CredentialsError < Error; end
+
+  # Raised when you try to locate an invalid address.
+  class AddressError < Error; end
+
+end

data/lib/graticule/geocoder/base.rb

@@ -0,0 +1,112 @@
+require 'open-uri'
+
+module Graticule #:nodoc:
+  module Geocoder
+
+    # Abstract class for implementing geocoders.
+    #
+    # === Example
+    #
+    # The following methods must be implemented in sublcasses:
+    #
+    # * +initialize+:: Sets @url to the service enpoint.
+    # * +check_error+:: Checks for errors in the server response.
+    # * +parse_response+:: Extracts information from the server response.
+    #
+    # Optionally, you can also override
+    #
+    # * +prepare_response+:: Convert the string response into a different format
+    #   that gets passed on to +check_error+ and +parse_response+.
+    #
+    # If you have extra URL paramaters (application id, output type) or need to
+    # perform URL customization, override +make_url+.
+    #
+    #   class FakeGeocoder < Base
+    #   
+    #     def initialize(appid)
+    #       @appid = appid
+    #       @url = URI.parse 'http://example.com/test'
+    #     end
+    #
+    #     def locate(query)
+    #       get :q => query
+    #     end
+    #   
+    #   private
+    #   
+    #     def check_error(xml)
+    #       raise Error, xml.elements['error'].text if xml.elements['error']
+    #     end
+    #   
+    #     def make_url(params)
+    #       params[:appid] = @appid
+    #       super params
+    #     end
+    #   
+    #     def parse_response(response)
+    #       # return Location
+    #     end
+    #   
+    #   end
+    #
+    class Base
+      USER_AGENT = "Mozilla/5.0 (compatible; Graticule/#{Graticule::Version::STRING}; http://graticule.rubyforge.org)"
+
+      def initialize
+        raise NotImplementedError
+      end
+      
+    private
+    
+      def location_from_params(params)
+        case params
+        when Location then params
+        when Hash then Location.new params
+        else
+          raise ArgumentError, "Expected a Graticule::Location or a hash with :street, :locality, :region, :postal_code, and :country attributes"
+        end
+      end
+
+      # Check for errors in +response+ and raise appropriate error, if any.
+      # Must return if no error could be found.
+      def check_error(response)
+        raise NotImplementedError
+      end
+
+      # Performs a GET request with +params+.  Calls +check_error+ and returns
+      # the result of +parse_response+.
+      def get(params = {})
+        response = prepare_response(make_url(params).open('User-Agent' => USER_AGENT).read)
+        check_error(response)
+        return parse_response(response)
+      rescue OpenURI::HTTPError => e
+        check_error(prepare_response(e.io.read))
+        raise
+      end
+
+      # Creates a URI from the Hash +params+.  Override this then call super if
+      # you need to add extra params like an application id or output type.
+      def make_url(params)
+        escaped_params = params.sort_by { |k,v| k.to_s }.map do |k,v|
+          "#{URI.escape k.to_s}=#{URI.escape v.to_s}"
+        end
+
+        url = @url.dup
+        url.query = escaped_params.join '&'
+        return url
+      end
+      
+      # Override to convert the response to something besides a String, which
+      # will get passed to +check_error+ and +parse_response+.
+      def prepare_response(response)
+        response
+      end
+
+      # Must parse results from +response+ into a Location.
+      def parse_response(response)
+        raise NotImplementedError
+      end
+
+    end
+  end
+end

data/lib/graticule/geocoder/bogus.rb

@@ -0,0 +1,15 @@
+module Graticule #:nodoc:
+  module Geocoder #:nodoc:
+
+    # Bogus geocoder that can be used for test purposes
+    class Bogus
+    
+      # returns a new location with the address set to the original query string
+      def locate(address)
+        Location.new :street => address
+      end
+    
+    end
+
+  end
+end