geocoder 0.1.1 → 0.9.8

data/lib/geocoder/active_record.rb

@@ -0,0 +1,235 @@
+##
+# Add geocoding functionality to any ActiveRecord object.
+#
+module Geocoder
+  module ActiveRecord
+
+    ##
+    # Implementation of 'included' hook method.
+    #
+    def self.included(base)
+      base.extend ClassMethods
+      base.class_eval do
+
+        # scope: geocoded objects
+        scope :geocoded,
+          :conditions => "#{geocoder_options[:latitude]} IS NOT NULL " +
+            "AND #{geocoder_options[:longitude]} IS NOT NULL"
+
+        # scope: not-geocoded objects
+        scope :not_geocoded,
+          :conditions => "#{geocoder_options[:latitude]} IS NULL " +
+            "OR #{geocoder_options[:longitude]} IS NULL"
+
+        ##
+        # Find all objects within a radius (in miles) of the given location
+        # (address string). Location (the first argument) may be either a string
+        # to geocode or an array of coordinates (<tt>[lat,long]</tt>).
+        #
+        scope :near, lambda{ |location, *args|
+          latitude, longitude = location.is_a?(Array) ?
+            location : Geocoder::Lookup.coordinates(location)
+          if latitude and longitude
+            near_scope_options(latitude, longitude, *args)
+          else
+            {}
+          end
+        }
+      end
+    end
+
+    ##
+    # Methods which will be class methods of the including class.
+    #
+    module ClassMethods
+
+      ##
+      # Get options hash suitable for passing to ActiveRecord.find to get
+      # records within a radius (in miles) of the given point.
+      # Options hash may include:
+      #
+      # +units+   :: <tt>:mi</tt> (default) or <tt>:km</tt>
+      # +exclude+ :: an object to exclude (used by the #nearbys method)
+      # +order+   :: column(s) for ORDER BY SQL clause
+      # +limit+   :: number of records to return (for LIMIT SQL clause)
+      # +offset+  :: number of records to skip (for OFFSET SQL clause)
+      # +select+  :: string with the SELECT SQL fragment (e.g. “id, name”)
+      #
+      def near_scope_options(latitude, longitude, radius = 20, options = {})
+        radius *= Geocoder::Calculations.km_in_mi if options[:units] == :km
+        if ::ActiveRecord::Base.connection.adapter_name == "SQLite"
+          approx_near_scope_options(latitude, longitude, radius, options)
+        else
+          full_near_scope_options(latitude, longitude, radius, options)
+        end
+      end
+
+
+      private # ----------------------------------------------------------------
+
+      ##
+      # Scope options hash for use with a database that supports POWER(),
+      # SQRT(), PI(), and trigonometric functions (SIN(), COS(), and ASIN()).
+      #
+      # Taken from the excellent tutorial at:
+      # http://www.scribd.com/doc/2569355/Geo-Distance-Search-with-MySQL
+      #
+      def full_near_scope_options(latitude, longitude, radius, options)
+        lat_attr = geocoder_options[:latitude]
+        lon_attr = geocoder_options[:longitude]
+        distance = "3956 * 2 * ASIN(SQRT(" +
+          "POWER(SIN((#{latitude} - #{lat_attr}) * " +
+          "PI() / 180 / 2), 2) + COS(#{latitude} * PI()/180) * " +
+          "COS(#{lat_attr} * PI() / 180) * " +
+          "POWER(SIN((#{longitude} - #{lon_attr}) * " +
+          "PI() / 180 / 2), 2) ))"
+        options[:order] ||= "#{distance} ASC"
+        default_near_scope_options(latitude, longitude, radius, options).merge(
+          :select => "#{options[:select] || '*'}, #{distance} AS distance",
+          :having => "#{distance} <= #{radius}"
+        )
+      end
+
+      ##
+      # Scope options hash for use with a database without trigonometric
+      # functions, like SQLite. Approach is to find objects within a square
+      # rather than a circle, so results are very approximate (will include
+      # objects outside the given radius).
+      #
+      def approx_near_scope_options(latitude, longitude, radius, options)
+        default_near_scope_options(latitude, longitude, radius, options).merge(
+          :select => options[:select] || nil
+        )
+      end
+
+      ##
+      # Options used for any near-like scope.
+      #
+      def default_near_scope_options(latitude, longitude, radius, options)
+        lat_attr = geocoder_options[:latitude]
+        lon_attr = geocoder_options[:longitude]
+        conditions = \
+          ["#{lat_attr} BETWEEN ? AND ? AND #{lon_attr} BETWEEN ? AND ?"] +
+          coordinate_bounds(latitude, longitude, radius)
+        if obj = options[:exclude]
+          conditions[0] << " AND id != ?"
+          conditions << obj.id
+        end
+        {
+          :group  => columns.map{ |c| "#{table_name}.#{c.name}" }.join(','),
+          :order  => options[:order],
+          :limit  => options[:limit],
+          :offset => options[:offset],
+          :conditions => conditions
+        }
+      end
+
+      ##
+      # Get the rough high/low lat/long bounds for a geographic point and
+      # radius. Returns an array: <tt>[lat_lo, lat_hi, lon_lo, lon_hi]</tt>.
+      # Used to constrain search to a (radius x radius) square.
+      #
+      def coordinate_bounds(latitude, longitude, radius)
+        radius = radius.to_f
+        factor = (Math::cos(latitude * Math::PI / 180.0) * 69.0).abs
+        [
+          latitude  - (radius / 69.0),
+          latitude  + (radius / 69.0),
+          longitude - (radius / factor),
+          longitude + (radius / factor)
+        ]
+      end
+    end
+
+    ##
+    # Read the coordinates [lat,lon] of an object. This is not great but it
+    # seems cleaner than polluting the instance method namespace.
+    #
+    def read_coordinates
+      [:latitude, :longitude].map{ |i| send self.class.geocoder_options[i] }
+    end
+
+    ##
+    # Is this object geocoded? (Does it have latitude and longitude?)
+    #
+    def geocoded?
+      read_coordinates.compact.size > 0
+    end
+
+    ##
+    # Calculate the distance from the object to a point (lat,lon).
+    #
+    # <tt>:units</tt> :: <tt>:mi</tt> (default) or <tt>:km</tt>
+    #
+    def distance_to(lat, lon, units = :mi)
+      return nil unless geocoded?
+      mylat,mylon = read_coordinates
+      Geocoder::Calculations.distance_between(mylat, mylon, lat, lon, :units => units)
+    end
+
+    ##
+    # Get other geocoded objects within a given radius.
+    #
+    # <tt>:units</tt> :: <tt>:mi</tt> (default) or <tt>:km</tt>
+    #
+    def nearbys(radius = 20, units = :mi)
+      return [] unless geocoded?
+      options = {:exclude => self, :units => units}
+      self.class.near(read_coordinates, radius, options)
+    end
+
+    ##
+    # Fetch coordinates and assign +latitude+ and +longitude+. Also returns
+    # coordinates as an array: <tt>[lat, lon]</tt>.
+    #
+    def fetch_coordinates(save = false)
+      address_method = self.class.geocoder_options[:user_address]
+      unless address_method.is_a? Symbol
+        raise Geocoder::ConfigurationError,
+          "You are attempting to fetch coordinates but have not specified " +
+          "a method which provides an address for the object."
+      end
+      coords = Geocoder::Lookup.coordinates(send(address_method))
+      unless coords.blank?
+        method = (save ? "update" : "write") + "_attribute"
+        send method, self.class.geocoder_options[:latitude],  coords[0]
+        send method, self.class.geocoder_options[:longitude], coords[1]
+      end
+      coords
+    end
+
+    ##
+    # Fetch coordinates and update (save) +latitude+ and +longitude+ data.
+    #
+    def fetch_coordinates!
+      fetch_coordinates(true)
+    end
+
+    ##
+    # Fetch address and assign +address+ attribute. Also returns
+    # address as a string.
+    #
+    def fetch_address(save = false)
+      lat_attr = self.class.geocoder_options[:latitude]
+      lon_attr = self.class.geocoder_options[:longitude]
+      unless lat_attr.is_a?(Symbol) and lon_attr.is_a?(Symbol)
+        raise Geocoder::ConfigurationError,
+          "You are attempting to fetch an address but have not specified " +
+          "attributes which provide coordinates for the object."
+      end
+      address = Geocoder::Lookup.address(send(lat_attr), send(lon_attr))
+      unless address.blank?
+        method = (save ? "update" : "write") + "_attribute"
+        send method, self.class.geocoder_options[:fetched_address], address
+      end
+      address
+    end
+
+    ##
+    # Fetch address and update (save) +address+ data.
+    #
+    def fetch_address!
+      fetch_address(true)
+    end
+  end
+end

data/lib/geocoder/calculations.rb

@@ -0,0 +1,94 @@
+module Geocoder
+  module Calculations
+    extend self
+
+    ##
+    # 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>
+    #
+    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)
+
+      # compute distances
+      dlat = (lat1 - lat2).abs
+      dlon = (lon1 - lon2).abs
+
+      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]]
+    end
+
+    ##
+    # Compute the geographic center (aka geographic midpoint, center of
+    # gravity) for an array of geocoded objects and/or [lat,lon] arrays
+    # (can be mixed). Any objects missing coordinates are ignored. Follows
+    # the procedure documented at http://www.geomidpoint.com/calculation.html.
+    #
+    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
+
+      # convert degrees to radians
+      points.map!{ |p| [to_radians(p[0]), to_radians(p[1])] }
+
+      # convert to Cartesian coordinates
+      x = []; y = []; z = []
+      points.each do |p|
+        x << Math.cos(p[0]) * Math.cos(p[1])
+        y << Math.cos(p[0]) * Math.sin(p[1])
+        z << Math.sin(p[0])
+      end
+
+      # compute average coordinate values
+      xa, ya, za = [x,y,z].map do |c|
+        c.inject(0){ |tot,i| tot += i } / c.size.to_f
+      end
+
+      # convert back to latitude/longitude
+      lon = Math.atan2(ya, xa)
+      hyp = Math.sqrt(xa**2 + ya**2)
+      lat = Math.atan2(za, hyp)
+
+      # return answer in degrees
+      [to_degrees(lat), to_degrees(lon)]
+    end
+
+    ##
+    # Convert degrees to radians.
+    #
+    def to_radians(degrees)
+      degrees * (Math::PI / 180)
+    end
+
+    ##
+    # Convert radians to degrees.
+    #
+    def to_degrees(radians)
+      (radians * 180.0) / Math::PI
+    end
+
+    ##
+    # Conversion factor: km to mi.
+    #
+    def km_in_mi
+      0.621371192
+    end
+  end
+end

data/lib/geocoder/configuration.rb

@@ -0,0 +1,8 @@
+module Geocoder
+  class Configuration
+    cattr_accessor :timeout
+  end
+end
+
+Geocoder::Configuration.timeout = 3
+

data/lib/geocoder/lookup.rb

@@ -0,0 +1,90 @@
+require 'net/http'
+
+module Geocoder
+  module Lookup
+    extend self
+
+    ##
+    # Query Google for the coordinates of the given address.
+    #
+    def coordinates(address)
+      if (results = search(address)).size > 0
+        place = results.first.geometry['location']
+        ['lat', 'lng'].map{ |i| place[i] }
+      end
+    end
+
+    ##
+    # Query Google for the address of the given coordinates.
+    #
+    def address(latitude, longitude)
+      if (results = search(latitude, longitude)).size > 0
+        results.first.formatted_address
+      end
+    end
+
+    ##
+    # Takes a search string (eg: "Mississippi Coast Coliseumf, Biloxi, MS") for
+    # geocoding, or coordinates (latitude, longitude) for reverse geocoding.
+    # Returns an array of Geocoder::Result objects,
+    # or nil if not found or if network error.
+    #
+    def search(*args)
+      return nil if args[0].blank?
+      doc = parsed_response(args.join(","), args.size == 2)
+      [].tap do |results|
+        if doc
+          doc['results'].each{ |r| results << Result.new(r) }
+        end
+      end
+    end
+
+
+    private # ---------------------------------------------------------------
+
+    ##
+    # Returns a parsed Google geocoder search result (hash).
+    # Returns nil if non-200 HTTP response, timeout, or other error.
+    #
+    def parsed_response(query, reverse = false)
+      begin
+        doc = ActiveSupport::JSON.decode(fetch_data(query, reverse))
+      rescue SocketError
+        warn "Google Geocoding API connection cannot be established."
+      rescue TimeoutError
+        warn "Google Geocoding API not responding fast enough " +
+          "(see Geocoder::Configuration.timeout to set limit)."
+      end
+
+      case doc['status']; when "OK"
+        doc
+      when "OVER_QUERY_LIMIT"
+        warn "Google Geocoding API error: over query limit."
+      when "REQUEST_DENIED"
+        warn "Google Geocoding API error: request denied."
+      when "INVALID_REQUEST"
+        warn "Google Geocoding API error: invalid request."
+      end
+    end
+
+    ##
+    # Fetches a raw Google geocoder search result (JSON string).
+    #
+    def fetch_data(query, reverse = false)
+      return nil if query.blank?
+      url = query_url(query, reverse)
+      timeout(Geocoder::Configuration.timeout) do
+        Net::HTTP.get_response(URI.parse(url)).body
+      end
+    end
+
+    def query_url(query, reverse = false)
+      params = {
+        (reverse ? :latlng : :address) => query,
+        :sensor => "false"
+      }
+      "http://maps.google.com/maps/api/geocode/json?" + params.to_query
+    end
+  end
+end
+

data/lib/geocoder/railtie.rb

@@ -0,0 +1,68 @@
+require 'geocoder'
+
+module Geocoder
+  if defined? Rails::Railtie
+    require 'rails'
+    class Railtie < Rails::Railtie
+      initializer 'geocoder.insert_into_active_record' do
+        ActiveSupport.on_load :active_record do
+          Geocoder::Railtie.insert
+        end
+      end
+      rake_tasks do
+        load "tasks/geocoder.rake"
+      end
+    end
+  end
+
+  class Railtie
+    def self.insert
+
+      return unless defined?(::ActiveRecord)
+
+      ##
+      # Add methods to ActiveRecord::Base so Geocoder is accessible by models.
+      #
+      ::ActiveRecord::Base.class_eval do
+
+        ##
+        # Set attribute names and include the Geocoder module.
+        #
+        def self.geocoded_by(address_attr, options = {})
+          _geocoder_init(
+            :user_address => address_attr,
+            :latitude  => options[:latitude]  || :latitude,
+            :longitude => options[:longitude] || :longitude
+          )
+        end
+
+        ##
+        # Set attribute names and include the Geocoder module.
+        #
+        def self.reverse_geocoded_by(latitude_attr, longitude_attr, options = {})
+          _geocoder_init(
+            :fetched_address => options[:address] || :address,
+            :latitude  => latitude_attr,
+            :longitude => longitude_attr
+          )
+        end
+
+        def self._geocoder_init(options)
+          unless _geocoder_initialized?
+            class_inheritable_reader :geocoder_options
+            class_inheritable_hash_writer :geocoder_options
+          end
+          self.geocoder_options = options
+          unless _geocoder_initialized?
+            include Geocoder::ActiveRecord
+          end
+        end
+
+        def self._geocoder_initialized?
+          included_modules.include? Geocoder::ActiveRecord
+        end
+      end
+
+    end
+  end
+end