geocoder 0.9.10 → 0.9.11

data/lib/geocoder/calculations.rb

@@ -2,34 +2,113 @@ module Geocoder
   module Calculations
     extend self
 
+    ##
+    # Compass point names, listed clockwise starting at North.
+    #
+    # If you want bearings named using more, fewer, or different points
+    # override Geocoder::Calculations.COMPASS_POINTS with your own array.
+    #
+    COMPASS_POINTS = %w[N NE E SE S SW W NW]
+
+    ##
+    # Radius of the Earth, in kilometers.
+    # Value taken from: http://en.wikipedia.org/wiki/Earth_radius
+    #
+    EARTH_RADIUS = 6371.0
+
+    ##
+    # Conversion factor: multiply by kilometers to get miles.
+    #
+    KM_IN_MI = 0.621371192
+
+    ##
+    # Calculate the distance spanned by one
+    # degree of latitude in the given units.
+    #
+    def latitude_degree_distance(units = :mi)
+      2 * Math::PI * earth_radius(units) / 360
+    end
+
+    ##
+    # Calculate the distance spanned by one degree of longitude
+    # at the given latitude. This ranges from around 69 miles at
+    # the equator to zero at the poles.
+    #
+    def longitude_degree_distance(latitude, units = :mi)
+      latitude_degree_distance(units) * Math.cos(to_radians(latitude))
+    end
+
     ##
     # Calculate the distance between two points on Earth (Haversine formula).
     # Takes two sets of coordinates and an options hash:
     #
-    # <tt>:units</tt> :: <tt>:mi</tt> (default) or <tt>:km</tt>
+    # * <tt>:units</tt> - <tt>:mi</tt> (default) or <tt>:km</tt>
     #
     def distance_between(lat1, lon1, lat2, lon2, options = {})
 
       # set default options
       options[:units] ||= :mi
 
-      # define conversion factors
-      conversions = { :mi => 3956, :km => 6371 }
-
       # convert degrees to radians
-      lat1 = to_radians(lat1)
-      lon1 = to_radians(lon1)
-      lat2 = to_radians(lat2)
-      lon2 = to_radians(lon2)
+      lat1, lon1, lat2, lon2 = to_radians(lat1, lon1, lat2, lon2)
 
-      # compute distances
-      dlat = (lat1 - lat2).abs
-      dlon = (lon1 - lon2).abs
+      # compute deltas
+      dlat = lat2 - lat1
+      dlon = lon2 - lon1
 
       a = (Math.sin(dlat / 2))**2 + Math.cos(lat1) *
           (Math.sin(dlon / 2))**2 * Math.cos(lat2)
       c = 2 * Math.atan2( Math.sqrt(a), Math.sqrt(1-a))
-      c * conversions[options[:units]]
+      c * earth_radius(options[:units])
+    end
+
+    ##
+    # Calculate bearing between two sets of coordinates.
+    # Returns a number of degrees from due north (clockwise).
+    #
+    # Also accepts an options hash:
+    #
+    # * <tt>:method</tt> - <tt>:linear</tt> (default) or <tt>:spherical</tt>;
+    #   the spherical method is "correct" in that it returns the shortest path
+    #   (one along a great circle) but the linear method is the default as it
+    #   is less confusing (returns due east or west when given two points with
+    #   the same latitude)
+    #
+    # Based on: http://www.movable-type.co.uk/scripts/latlong.html
+    #
+    def bearing_between(lat1, lon1, lat2, lon2, options = {})
+      options[:method] = :linear unless options[:method] == :spherical
+
+      # convert degrees to radians
+      lat1, lon1, lat2, lon2 = to_radians(lat1, lon1, lat2, lon2)
+
+      # compute deltas
+      dlat = lat2 - lat1
+      dlon = lon2 - lon1
+
+      case options[:method]
+      when :linear
+        y = dlon
+        x = dlat
+
+      when :spherical
+        y = Math.sin(dlon) * Math.cos(lat2)
+        x = Math.cos(lat1) * Math.sin(lat2) -
+            Math.sin(lat1) * Math.cos(lat2) * Math.cos(dlon)
+      end
+
+      bearing = Math.atan2(x,y)
+      # Answer is in radians counterclockwise from due east.
+      # Convert to degrees clockwise from due north:
+      (90 - to_degrees(bearing) + 360) % 360
+    end
+
+    ##
+    # Translate a bearing (float) into a compass direction (string, eg "North").
+    #
+    def compass_point(bearing, points = COMPASS_POINTS)
+      seg_size = 360 / points.size
+      points[((bearing + (seg_size / 2)) % 360) / seg_size]
     end
 
     ##
@@ -41,12 +120,10 @@ module Geocoder
     def geographic_center(points)
 
       # convert objects to [lat,lon] arrays and remove nils
-      points = points.map{ |p|
-        p.is_a?(Array) ? p : (p.geocoded?? p.read_coordinates : nil)
-      }.compact
+      points.map!{ |p| p.is_a?(Array) ? p : p.to_coordinates }.compact
 
       # convert degrees to radians
-      points.map!{ |p| [to_radians(p[0]), to_radians(p[1])] }
+      points.map!{ |p| to_radians(p) }
 
       # convert to Cartesian coordinates
       x = []; y = []; z = []
@@ -67,28 +144,91 @@ module Geocoder
       lat = Math.atan2(za, hyp)
 
       # return answer in degrees
-      [to_degrees(lat), to_degrees(lon)]
+      to_degrees [lat, lon]
+    end
+
+    ##
+    # Returns coordinates of the lower-left and upper-right corners of a box
+    # with the given point at its center. The radius is the shortest distance
+    # from the center point to any side of the box (the length of each side
+    # is twice the radius).
+    #
+    # This is useful for finding corner points of a map viewport, or for
+    # roughly limiting the possible solutions in a geo-spatial search
+    # (ActiveRecord queries use it thusly).
+    #
+    def bounding_box(latitude, longitude, radius, options = {})
+      units = options[:units] || :mi
+      radius = radius.to_f
+      [
+        latitude  - (radius / latitude_degree_distance(units)),
+        longitude - (radius / longitude_degree_distance(latitude, units)),
+        latitude  + (radius / latitude_degree_distance(units)),
+        longitude + (radius / longitude_degree_distance(latitude, units))
+      ]
     end
 
     ##
     # Convert degrees to radians.
+    # If an array (or multiple arguments) is passed,
+    # converts each value and returns array.
     #
-    def to_radians(degrees)
-      degrees * (Math::PI / 180)
+    def to_radians(*args)
+      args = args.first if args.first.is_a?(Array)
+      if args.size == 1
+        args.first * (Math::PI / 180)
+      else
+        args.map{ |i| to_radians(i) }
+      end
     end
 
     ##
     # Convert radians to degrees.
+    # If an array (or multiple arguments) is passed,
+    # converts each value and returns array.
+    #
+    def to_degrees(*args)
+      args = args.first if args.first.is_a?(Array)
+      if args.size == 1
+        (args.first * 180.0) / Math::PI
+      else
+        args.map{ |i| to_degrees(i) }
+      end
+    end
+
+    ##
+    # Convert miles to kilometers.
+    #
+    def to_kilometers(mi)
+      mi * mi_in_km
+    end
+
+    ##
+    # Convert kilometers to miles.
     #
-    def to_degrees(radians)
-      (radians * 180.0) / Math::PI
+    def to_miles(km)
+      km * km_in_mi
+    end
+
+    ##
+    # Radius of the Earth in the given units (:mi or :km). Default is :mi.
+    #
+    def earth_radius(units = :mi)
+      units == :km ? EARTH_RADIUS : to_miles(EARTH_RADIUS)
     end
 
     ##
     # Conversion factor: km to mi.
     #
     def km_in_mi
-      0.621371192
+      KM_IN_MI
+    end
+
+    ##
+    # Conversion factor: mi to km.
+    #
+    def mi_in_km
+      1.0 / KM_IN_MI
     end
   end
 end

data/lib/geocoder/configuration.rb

@@ -1,16 +1,53 @@
 module Geocoder
   class Configuration
-    def self.timeout; @@timeout; end
-    def self.timeout=(obj); @@timeout = obj; end
 
-    def self.lookup; @@lookup; end
-    def self.lookup=(obj); @@lookup = obj; end
+    def self.options_and_defaults
+      [
+        # geocoding service timeout (secs)
+        [:timeout, 3],
 
-    def self.yahoo_appid; @@yahoo_appid; end
-    def self.yahoo_appid=(obj); @@yahoo_appid = obj; end
+        # name of geocoding service (symbol)
+        [:lookup, :google],
+
+        # ISO-639 language code
+        [:language, :en],
+
+        # use HTTPS for lookup requests? (if supported)
+        [:use_https, false],
+
+        # API key for geocoding service
+        [:api_key, nil],
+
+        # cache object (must respond to #[], #[]=, and #keys)
+        [:cache, nil],
+
+        # prefix (string) to use for all cache keys
+        [:cache_prefix, "geocoder:"]
+      ]
+    end
+
+    # define getters and setters for all configuration settings
+    self.options_and_defaults.each do |o,d|
+      eval("def self.#{o}; @@#{o}; end")
+      eval("def self.#{o}=(obj); @@#{o} = obj; end")
+    end
+
+    # legacy support
+    def self.yahoo_app_id=(value)
+      warn "DEPRECATION WARNING: Geocoder's 'yahoo_app_id' setting has been replaced by 'api_key'. " +
+        "This method will be removed in Geocoder v1.0."
+      @@api_key = value
+    end
+
+    ##
+    # Set all values to default.
+    #
+    def self.set_defaults
+      self.options_and_defaults.each do |o,d|
+        self.send("#{o}=", d)
+      end
+    end
   end
 end
 
-Geocoder::Configuration.timeout     = 3
-Geocoder::Configuration.lookup      = :google
-Geocoder::Configuration.yahoo_appid = ""
+Geocoder::Configuration.set_defaults

data/lib/geocoder/lookups/base.rb

@@ -1,6 +1,7 @@
 require 'net/http'
 unless defined?(ActiveSupport::JSON)
   begin
+    require 'rubygems' # for Ruby 1.8
     require 'json'
   rescue LoadError
     raise LoadError, "Please install the 'json' or 'json_pure' gem to parse geocoder results."
@@ -17,12 +18,11 @@ module Geocoder
       #
       # Takes a search string (eg: "Mississippi Coast Coliseumf, Biloxi, MS",
       # "205.128.54.202") for geocoding, or coordinates (latitude, longitude)
-      # for reverse geocoding.
+      # for reverse geocoding. Returns an array of <tt>Geocoder::Result</tt>s.
       #
       def search(*args)
-        if res = result(args.join(","), args.size == 2)
-          result_class.new(res)
-        end
+        reverse = (args.size == 2) || coordinates?(args.first)
+        results(args.join(","), reverse).map{ |r| result_class.new(r) }
       end
 
 
@@ -31,7 +31,7 @@ module Geocoder
       ##
       # Geocoder::Result object or nil on timeout or other error.
       #
-      def result(query, reverse = false)
+      def results(query, reverse = false)
         fail
       end
 
@@ -60,7 +60,7 @@ module Geocoder
         rescue TimeoutError
           warn "Geocoding API not responding fast enough " +
             "(see Geocoder::Configuration.timeout to set limit)."
-        end
+      end
       end
 
       ##
@@ -78,16 +78,37 @@ module Geocoder
         end
       end
 
+      ##
+      # Protocol to use for communication with geocoding services.
+      # Set in configuration but not available for every service.
+      #
+      def protocol
+        "http" + (Geocoder::Configuration.use_https ? "s" : "")
+      end
+
       ##
       # Fetches a raw search result (JSON string).
       #
       def fetch_raw_data(query, reverse = false)
-        url = query_url(query, reverse)
         timeout(Geocoder::Configuration.timeout) do
-          Net::HTTP.get_response(URI.parse(url)).body
+          url = query_url(query, reverse)
+          unless cache and response = cache[url]
+            response = Net::HTTP.get_response(URI.parse(url)).body
+            if cache
+              cache[url] = response
+            end
+          end
+          response
         end
       end
 
+      ##
+      # The working Cache object.
+      #
+      def cache
+        Geocoder.cache
+      end
+
       ##
       # Is the given string a loopback IP address?
       #
@@ -95,12 +116,22 @@ module Geocoder
         !!(ip == "0.0.0.0" or ip.match(/^127/))
       end
 
+      ##
+      # Does the given string look like latitude/longitude coordinates?
+      #
+      def coordinates?(value)
+        !!value.to_s.match(/^[0-9\.\-]+, ?[0-9\.\-]+$/)
+      end
+
       ##
       # Simulate ActiveSupport's Object#to_query.
+      # Removes any keys with nil value.
       #
       def hash_to_query(hash)
         require 'cgi' unless defined?(CGI) && defined?(CGI.escape)
-        hash.collect{ |p| p.map{ |i| CGI.escape i.to_s } * '=' }.sort * '&'
+        hash.collect{ |p|
+          p[1].nil? ? nil : p.map{ |i| CGI.escape i.to_s } * '='
+        }.compact.sort * '&'
       end
     end
   end

data/lib/geocoder/lookups/freegeoip.rb

@@ -6,15 +6,13 @@ module Geocoder::Lookup
 
     private # ---------------------------------------------------------------
 
-    def result(query, reverse = false)
+    def results(query, reverse = false)
       # don't look up a loopback address, just return the stored result
-      return reserved_result(query) if loopback_address?(query)
+      return [reserved_result(query)] if loopback_address?(query)
       begin
-        if doc = fetch_data(query, reverse)
-          doc
-        end
+        return [fetch_data(query, reverse)]
       rescue StandardError # Freegeoip.net returns HTML on bad request
-        nil
+        return []
       end
     end
 

data/lib/geocoder/lookups/geocoder_ca.rb

@@ -0,0 +1,44 @@
+require 'geocoder/lookups/base'
+require "geocoder/results/geocoder_ca"
+
+module Geocoder::Lookup
+  class GeocoderCa < Base
+
+    private # ---------------------------------------------------------------
+
+    def results(query, reverse = false)
+      return [] unless doc = fetch_data(query, reverse)
+      if doc['error'].nil?
+        return [doc]
+      elsif doc['error']['code'] == "005"
+        # "Postal Code is not in the proper Format" => no results, just shut up
+      else
+        warn "Geocoder.ca service error: #{doc['error']['code']} (#{doc['error']['description']})."
+      end
+      return []
+    end
+
+    def query_url(query, reverse = false)
+      params = {
+        :geoit    => "xml",
+        :jsonp    => 1,
+        :callback => "test"
+      }
+      if reverse
+        lat,lon = query.split(',')
+        params[:latt] = lat
+        params[:longt] = lon
+        params[:corner] = 1
+        params[:reverse] = 1
+      else
+        params[:locate] = query
+      end
+      "http://geocoder.ca/?" + hash_to_query(params)
+    end
+
+    def parse_raw_data(raw_data)
+      super raw_data[/^test\((.*)\)\;\s*$/, 1]
+    end
+  end
+end
+