geocoder2 0.1.0

data/lib/geocoder2/sql.rb

@@ -0,0 +1,106 @@
+module Geocoder2
+  module Sql
+    extend self
+
+    ##
+    # Distance calculation for use with a database that supports POWER(),
+    # SQRT(), PI(), and trigonometric functions SIN(), COS(), ASIN(),
+    # ATAN2(), DEGREES(), and RADIANS().
+    #
+    # Based on the excellent tutorial at:
+    # http://www.scribd.com/doc/2569355/Geo-Distance-Search-with-MySQL
+    #
+    def full_distance(latitude, longitude, lat_attr, lon_attr, options = {})
+      units = options[:units] || Geocoder2.config.units
+      earth = Geocoder2::Calculations.earth_radius(units)
+
+      "#{earth} * 2 * ASIN(SQRT(" +
+        "POWER(SIN((#{latitude.to_f} - #{lat_attr}) * PI() / 180 / 2), 2) + " +
+        "COS(#{latitude.to_f} * PI() / 180) * COS(#{lat_attr} * PI() / 180) * " +
+        "POWER(SIN((#{longitude.to_f} - #{lon_attr}) * PI() / 180 / 2), 2)" +
+      "))"
+    end
+
+    ##
+    # Distance calculation 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).
+    #
+    # Distance and bearing calculations are *extremely inaccurate*. To be
+    # clear: this only exists to provide interface consistency. Results
+    # are not intended for use in production!
+    #
+    def approx_distance(latitude, longitude, lat_attr, lon_attr, options = {})
+      units = options[:units] || Geocoder2.config.units
+      dx = Geocoder2::Calculations.longitude_degree_distance(30, units)
+      dy = Geocoder2::Calculations.latitude_degree_distance(units)
+
+      # sin of 45 degrees = average x or y component of vector
+      factor = Math.sin(Math::PI / 4)
+
+      "(#{dy} * ABS(#{lat_attr} - #{latitude.to_f}) * #{factor}) + " +
+        "(#{dx} * ABS(#{lon_attr} - #{longitude.to_f}) * #{factor})"
+    end
+
+    def within_bounding_box(sw_lat, sw_lng, ne_lat, ne_lng, lat_attr, lon_attr)
+      spans = "#{lat_attr} BETWEEN #{sw_lat} AND #{ne_lat} AND "
+      # handle box that spans 180 longitude
+      if sw_lng.to_f > ne_lng.to_f
+        spans + "#{lon_attr} BETWEEN #{sw_lng} AND 180 OR " +
+        "#{lon_attr} BETWEEN -180 AND #{ne_lng}"
+      else
+        spans + "#{lon_attr} BETWEEN #{sw_lng} AND #{ne_lng}"
+      end
+    end
+
+    ##
+    # Fairly accurate bearing calculation. Takes a latitude, longitude,
+    # and an options hash which must include a :bearing value
+    # (:linear or :spherical).
+    #
+    # Based on:
+    # http://www.beginningspatial.com/calculating_bearing_one_point_another
+    #
+    def full_bearing(latitude, longitude, lat_attr, lon_attr, options = {})
+      case options[:bearing] || Geocoder2.config.distances
+      when :linear
+        "CAST(" +
+          "DEGREES(ATAN2( " +
+            "RADIANS(#{lon_attr} - #{longitude.to_f}), " +
+            "RADIANS(#{lat_attr} - #{latitude.to_f})" +
+          ")) + 360 " +
+        "AS decimal) % 360"
+      when :spherical
+        "CAST(" +
+          "DEGREES(ATAN2( " +
+            "SIN(RADIANS(#{lon_attr} - #{longitude.to_f})) * " +
+            "COS(RADIANS(#{lat_attr})), (" +
+              "COS(RADIANS(#{latitude.to_f})) * SIN(RADIANS(#{lat_attr}))" +
+            ") - (" +
+              "SIN(RADIANS(#{latitude.to_f})) * COS(RADIANS(#{lat_attr})) * " +
+              "COS(RADIANS(#{lon_attr} - #{longitude.to_f}))" +
+            ")" +
+          ")) + 360 " +
+        "AS decimal) % 360"
+      end
+    end
+
+    ##
+    # Totally lame bearing calculation. Basically useless except that it
+    # returns *something* in databases without trig functions.
+    #
+    def approx_bearing(latitude, longitude, lat_attr, lon_attr, options = {})
+      "CASE " +
+        "WHEN (#{lat_attr} >= #{latitude.to_f} AND " +
+          "#{lon_attr} >= #{longitude.to_f}) THEN  45.0 " +
+        "WHEN (#{lat_attr} <  #{latitude.to_f} AND " +
+          "#{lon_attr} >= #{longitude.to_f}) THEN 135.0 " +
+        "WHEN (#{lat_attr} <  #{latitude.to_f} AND " +
+          "#{lon_attr} <  #{longitude.to_f}) THEN 225.0 " +
+        "WHEN (#{lat_attr} >= #{latitude.to_f} AND " +
+          "#{lon_attr} <  #{longitude.to_f}) THEN 315.0 " +
+      "END"
+    end
+  end
+end

data/lib/geocoder2/stores/active_record.rb

@@ -0,0 +1,272 @@
+# -*- coding: utf-8 -*-
+require 'geocoder2/sql'
+require 'geocoder2/stores/base'
+
+##
+# Add geocoding functionality to any ActiveRecord object.
+#
+module Geocoder2::Store
+  module ActiveRecord
+    include Base
+
+    ##
+    # Implementation of 'included' hook method.
+    #
+    def self.included(base)
+      base.extend ClassMethods
+      base.class_eval do
+
+        # scope: geocoded objects
+        scope :geocoded, lambda {
+          where("#{geocoder2_options[:latitude]} IS NOT NULL " +
+            "AND #{geocoder2_options[:longitude]} IS NOT NULL")
+        }
+
+        # scope: not-geocoded objects
+        scope :not_geocoded, lambda {
+          where("#{geocoder2_options[:latitude]} IS NULL " +
+            "OR #{geocoder2_options[:longitude]} IS NULL")
+        }
+
+        ##
+        # Find all objects within a radius of the given location.
+        # Location may be either a string to geocode or an array of
+        # coordinates (<tt>[lat,lon]</tt>). Also takes an options hash
+        # (see Geocoder2::Store::ActiveRecord::ClassMethods.near_scope_options
+        # for details).
+        #
+        scope :near, lambda{ |location, *args|
+          latitude, longitude = Geocoder2::Calculations.extract_coordinates(location)
+          if Geocoder2::Calculations.coordinates_present?(latitude, longitude)
+            options = near_scope_options(latitude, longitude, *args)
+            select(options[:select]).where(options[:conditions]).
+              order(options[:order])
+          else
+            # If no lat/lon given we don't want any results, but we still
+            # need distance and bearing columns so you can add, for example:
+            # .order("distance")
+            select(select_clause(nil, "NULL", "NULL")).where(false_condition)
+          end
+        }
+
+        ##
+        # Find all objects within the area of a given bounding box.
+        # Bounds must be an array of locations specifying the southwest
+        # corner followed by the northeast corner of the box
+        # (<tt>[[sw_lat, sw_lon], [ne_lat, ne_lon]]</tt>).
+        #
+        scope :within_bounding_box, lambda{ |bounds|
+          sw_lat, sw_lng, ne_lat, ne_lng = bounds.flatten if bounds
+          if sw_lat && sw_lng && ne_lat && ne_lng
+            where(Geocoder2::Sql.within_bounding_box(
+              sw_lat, sw_lng, ne_lat, ne_lng,
+              full_column_name(geocoder2_options[:latitude]),
+              full_column_name(geocoder2_options[:longitude])
+            ))
+          else
+            select(select_clause(nil, "NULL", "NULL")).where(false_condition)
+          end
+        }
+      end
+    end
+
+    ##
+    # Methods which will be class methods of the including class.
+    #
+    module ClassMethods
+
+      def distance_from_sql(location, *args)
+        latitude, longitude = Geocoder2::Calculations.extract_coordinates(location)
+        if Geocoder2::Calculations.coordinates_present?(latitude, longitude)
+          distance_sql(latitude, longitude, *args)
+        end
+      end
+
+      private # ----------------------------------------------------------------
+
+      ##
+      # Get options hash suitable for passing to ActiveRecord.find to get
+      # records within a radius (in kilometers) of the given point.
+      # Options hash may include:
+      #
+      # * +:units+   - <tt>:mi</tt> or <tt>:km</tt>; to be used.
+      #   for interpreting radius as well as the +distance+ attribute which
+      #   is added to each found nearby object.
+      #   Use Geocoder2.configure[:units] to configure default units.
+      # * +:bearing+ - <tt>:linear</tt> or <tt>:spherical</tt>.
+      #   the method to be used for calculating the bearing (direction)
+      #   between the given point and each found nearby point;
+      #   set to false for no bearing calculation. Use
+      #   Geocoder2.configure[:distances] to configure default calculation method.
+      # * +:select+          - string with the SELECT SQL fragment (e.g. “id, name”)
+      # * +:select_distance+ - whether to include the distance alias in the
+      #                        SELECT SQL fragment (e.g. <formula> AS distance)
+      # * +:select_bearing+  - like +:select_distance+ but for bearing.
+      # * +:order+           - column(s) for ORDER BY SQL clause; default is distance;
+      #                        set to false or nil to omit the ORDER BY clause
+      # * +:exclude+         - an object to exclude (used by the +nearbys+ method)
+      # * +:distance_column+ - used to set the column name of the calculated distance.
+      # * +:bearing_column+  - used to set the column name of the calculated bearing.
+      #
+      def near_scope_options(latitude, longitude, radius = 20, options = {})
+        if options[:units]
+          options[:units] = options[:units].to_sym
+        end
+        options[:units] ||= (geocoder2_options[:units] || Geocoder2.config.units)
+        select_distance = options.fetch(:select_distance, true)
+        options[:order] = "" if !select_distance && !options.include?(:order)
+        select_bearing = options.fetch(:select_bearing, true)
+        bearing = bearing_sql(latitude, longitude, options)
+        distance = distance_sql(latitude, longitude, options)
+        distance_column = options.fetch(:distance_column, 'distance')
+        bearing_column = options.fetch(:bearing_column, 'bearing')
+
+        b = Geocoder2::Calculations.bounding_box([latitude, longitude], radius, options)
+        args = b + [
+          full_column_name(geocoder2_options[:latitude]),
+          full_column_name(geocoder2_options[:longitude])
+        ]
+        bounding_box_conditions = Geocoder2::Sql.within_bounding_box(*args)
+
+        if using_sqlite?
+          conditions = bounding_box_conditions
+        else
+          conditions = [bounding_box_conditions + " AND #{distance} <= ?", radius]
+        end
+        {
+          :select => select_clause(options[:select],
+                                   select_distance ? distance : nil,
+                                   select_bearing ? bearing : nil,
+                                   distance_column,
+                                   bearing_column),
+          :conditions => add_exclude_condition(conditions, options[:exclude]),
+          :order => options.include?(:order) ? options[:order] : "#{distance_column} ASC"
+        }
+      end
+
+      ##
+      # SQL for calculating distance based on the current database's
+      # capabilities (trig functions?).
+      #
+      def distance_sql(latitude, longitude, options = {})
+        method_prefix = using_sqlite? ? "approx" : "full"
+        Geocoder2::Sql.send(
+          method_prefix + "_distance",
+          latitude, longitude,
+          full_column_name(geocoder2_options[:latitude]),
+          full_column_name(geocoder2_options[:longitude]),
+          options
+        )
+      end
+
+      ##
+      # SQL for calculating bearing based on the current database's
+      # capabilities (trig functions?).
+      #
+      def bearing_sql(latitude, longitude, options = {})
+        if !options.include?(:bearing)
+          options[:bearing] = Geocoder2.config.distances
+        end
+        if options[:bearing]
+          method_prefix = using_sqlite? ? "approx" : "full"
+          Geocoder2::Sql.send(
+            method_prefix + "_bearing",
+            latitude, longitude,
+            full_column_name(geocoder2_options[:latitude]),
+            full_column_name(geocoder2_options[:longitude]),
+            options
+          )
+        end
+      end
+
+      ##
+      # Generate the SELECT clause.
+      #
+      def select_clause(columns, distance = nil, bearing = nil, distance_column = 'distance', bearing_column = 'bearing')
+        if columns == :id_only
+          return full_column_name(primary_key)
+        elsif columns == :geo_only
+          clause = ""
+        else
+          clause = (columns || full_column_name("*"))
+        end
+        if distance
+          clause += ", " unless clause.empty?
+          clause += "#{distance} AS #{distance_column}"
+        end
+        if bearing
+          clause += ", " unless clause.empty?
+          clause += "#{bearing} AS #{bearing_column}"
+        end
+        clause
+      end
+
+      ##
+      # Adds a condition to exclude a given object by ID.
+      # Expects conditions as an array or string. Returns array.
+      #
+      def add_exclude_condition(conditions, exclude)
+        conditions = [conditions] if conditions.is_a?(String)
+        if exclude
+          conditions[0] << " AND #{full_column_name(primary_key)} != ?"
+          conditions << exclude.id
+        end
+        conditions
+      end
+
+      def using_sqlite?
+        connection.adapter_name.match /sqlite/i
+      end
+
+      ##
+      # Value which can be passed to where() to produce no results.
+      #
+      def false_condition
+        using_sqlite? ? 0 : "false"
+      end
+
+      ##
+      # Prepend table name if column name doesn't already contain one.
+      #
+      def full_column_name(column)
+        column = column.to_s
+        column.include?(".") ? column : [table_name, column].join(".")
+      end
+    end
+
+    ##
+    # Look up coordinates and assign to +latitude+ and +longitude+ attributes
+    # (or other as specified in +geocoded_by+). Returns coordinates (array).
+    #
+    def geocode
+      do_lookup(false) do |o,rs|
+        if r = rs.first
+          unless r.latitude.nil? or r.longitude.nil?
+            o.__send__  "#{self.class.geocoder2_options[:latitude]}=",  r.latitude
+            o.__send__  "#{self.class.geocoder2_options[:longitude]}=", r.longitude
+          end
+          r.coordinates
+        end
+      end
+    end
+
+    alias_method :fetch_coordinates, :geocode
+
+    ##
+    # Look up address and assign to +address+ attribute (or other as specified
+    # in +reverse_geocoded_by+). Returns address (string).
+    #
+    def reverse_geocode
+      do_lookup(true) do |o,rs|
+        if r = rs.first
+          unless r.address.nil?
+            o.__send__ "#{self.class.geocoder2_options[:fetched_address]}=", r.address
+          end
+          r.address
+        end
+      end
+    end
+
+    alias_method :fetch_address, :reverse_geocode
+  end
+end

data/lib/geocoder2/stores/base.rb

@@ -0,0 +1,120 @@
+module Geocoder2
+  module Store
+    module Base
+
+      ##
+      # Is this object geocoded? (Does it have latitude and longitude?)
+      #
+      def geocoded?
+        to_coordinates.compact.size > 0
+      end
+
+      ##
+      # Coordinates [lat,lon] of the object.
+      #
+      def to_coordinates
+        [:latitude, :longitude].map{ |i| send self.class.geocoder2_options[i] }
+      end
+
+      ##
+      # Calculate the distance from the object to an arbitrary point.
+      # See Geocoder2::Calculations.distance_between for ways of specifying
+      # the point. Also takes a symbol specifying the units
+      # (:mi or :km; can be specified in Geocoder2 configuration).
+      #
+      def distance_to(point, units = nil)
+        units ||= self.class.geocoder2_options[:units]
+        return nil unless geocoded?
+        Geocoder2::Calculations.distance_between(
+          to_coordinates, point, :units => units)
+      end
+
+      alias_method :distance_from, :distance_to
+
+      ##
+      # Calculate the bearing from the object to another point.
+      # See Geocoder2::Calculations.distance_between for
+      # ways of specifying the point.
+      #
+      def bearing_to(point, options = {})
+        options[:method] ||= self.class.geocoder2_options[:method]
+        return nil unless geocoded?
+        Geocoder2::Calculations.bearing_between(
+          to_coordinates, point, options)
+      end
+
+      ##
+      # Calculate the bearing from another point to the object.
+      # See Geocoder2::Calculations.distance_between for
+      # ways of specifying the point.
+      #
+      def bearing_from(point, options = {})
+        options[:method] ||= self.class.geocoder2_options[:method]
+        return nil unless geocoded?
+        Geocoder2::Calculations.bearing_between(
+          point, to_coordinates, options)
+      end
+
+      ##
+      # Get nearby geocoded objects.
+      # Takes the same options hash as the near class method (scope).
+      # Returns nil if the object is not geocoded.
+      #
+      def nearbys(radius = 20, options = {})
+        return nil unless geocoded?
+        options.merge!(:exclude => self) unless send(self.class.primary_key).nil?
+        self.class.near(self, radius, options)
+      end
+
+      ##
+      # Look up coordinates and assign to +latitude+ and +longitude+ attributes
+      # (or other as specified in +geocoded_by+). Returns coordinates (array).
+      #
+      def geocode
+        fail
+      end
+
+      ##
+      # Look up address and assign to +address+ attribute (or other as specified
+      # in +reverse_geocoded_by+). Returns address (string).
+      #
+      def reverse_geocode
+        fail
+      end
+
+      private # --------------------------------------------------------------
+
+      ##
+      # Look up geographic data based on object attributes (configured in
+      # geocoded_by or reverse_geocoded_by) and handle the results with the
+      # block (given to geocoded_by or reverse_geocoded_by). The block is
+      # given two-arguments: the object being geocoded and an array of
+      # Geocoder2::Result objects).
+      #
+      def do_lookup(reverse = false)
+        options = self.class.geocoder2_options
+        if reverse and options[:reverse_geocode]
+          query = to_coordinates
+        elsif !reverse and options[:geocode]
+          query = send(options[:user_address])
+        else
+          return
+        end
+
+        results = Geocoder2.search(query)
+
+        # execute custom block, if specified in configuration
+        block_key = reverse ? :reverse_block : :geocode_block
+        if custom_block = options[block_key]
+          custom_block.call(self, results)
+
+        # else execute block passed directly to this method,
+        # which generally performs the "auto-assigns"
+        elsif block_given?
+          yield(self, results)
+        end
+      end
+    end
+  end
+end
+

data/lib/geocoder2/stores/mongo_base.rb

@@ -0,0 +1,89 @@
+module Geocoder2::Store
+  module MongoBase
+
+    def self.included_by_model(base)
+      base.class_eval do
+
+        scope :geocoded, lambda {
+          where(geocoder2_options[:coordinates].ne => nil)
+        }
+
+        scope :not_geocoded, lambda {
+          where(geocoder2_options[:coordinates] => nil)
+        }
+
+        scope :near, lambda{ |location, *args|
+          coords  = Geocoder2::Calculations.extract_coordinates(location)
+
+          # no results if no lat/lon given
+          return where(:id => false) unless coords.is_a?(Array)
+
+          radius  = args.size > 0 ? args.shift : 20
+          options = args.size > 0 ? args.shift : {}
+          options[:units] ||= geocoder2_options[:units]
+
+          # Use BSON::OrderedHash if Ruby's hashes are unordered.
+          # Conditions must be in order required by indexes (see mongo gem).
+          version = RUBY_VERSION.split('.').map { |i| i.to_i }
+          empty = version[0] < 2 && version[1] < 9 ? BSON::OrderedHash.new : {}
+
+          conds = empty.clone
+          field = geocoder2_options[:coordinates]
+          conds[field] = empty.clone
+          conds[field]["$nearSphere"]  = coords.reverse
+
+          if radius
+            conds[field]["$maxDistance"] = \
+              Geocoder2::Calculations.distance_to_radians(radius, options[:units])
+          end
+
+          if obj = options[:exclude]
+            conds[:_id.ne] = obj.id
+          end
+          where(conds)
+        }
+      end
+    end
+
+    ##
+    # Coordinates [lat,lon] of the object.
+    # This method always returns coordinates in lat,lon order,
+    # even though internally they are stored in the opposite order.
+    #
+    def to_coordinates
+      coords = send(self.class.geocoder2_options[:coordinates])
+      coords.is_a?(Array) ? coords.reverse : []
+    end
+
+    ##
+    # Look up coordinates and assign to +latitude+ and +longitude+ attributes
+    # (or other as specified in +geocoded_by+). Returns coordinates (array).
+    #
+    def geocode
+      do_lookup(false) do |o,rs|
+        if r = rs.first
+          unless r.coordinates.nil?
+            o.__send__ "#{self.class.geocoder2_options[:coordinates]}=", r.coordinates.reverse
+          end
+          r.coordinates
+        end
+      end
+    end
+
+    ##
+    # Look up address and assign to +address+ attribute (or other as specified
+    # in +reverse_geocoded_by+). Returns address (string).
+    #
+    def reverse_geocode
+      do_lookup(true) do |o,rs|
+        if r = rs.first
+          unless r.address.nil?
+            o.__send__ "#{self.class.geocoder2_options[:fetched_address]}=", r.address
+          end
+          r.address
+        end
+      end
+    end
+  end
+end
+

data/lib/geocoder2/stores/mongo_mapper.rb

@@ -0,0 +1,13 @@
+require 'geocoder2/stores/base'
+require 'geocoder2/stores/mongo_base'
+
+module Geocoder2::Store
+  module MongoMapper
+    include Base
+    include MongoBase
+
+    def self.included(base)
+      MongoBase.included_by_model(base)
+    end
+  end
+end

data/lib/geocoder2/stores/mongoid.rb

@@ -0,0 +1,13 @@
+require 'geocoder2/stores/base'
+require 'geocoder2/stores/mongo_base'
+
+module Geocoder2::Store
+  module Mongoid
+    include Base
+    include MongoBase
+
+    def self.included(base)
+      MongoBase.included_by_model(base)
+    end
+  end
+end

data/lib/geocoder2/version.rb

@@ -0,0 +1,3 @@
+module Geocoder2
+  VERSION = "0.1.0"
+end

data/lib/geocoder2.rb

@@ -0,0 +1,55 @@
+require "geocoder2/configuration"
+require "geocoder2/query"
+require "geocoder2/calculations"
+require "geocoder2/exceptions"
+require "geocoder2/cache"
+require "geocoder2/request"
+require "geocoder2/lookup"
+require "geocoder2/models/active_record" if defined?(::ActiveRecord)
+require "geocoder2/models/mongoid" if defined?(::Mongoid)
+require "geocoder2/models/mongo_mapper" if defined?(::MongoMapper)
+
+module Geocoder2
+  extend self
+
+  ##
+  # Search for information about an address or a set of coordinates.
+  #
+  def search(query, options = {})
+    query = Geocoder2::Query.new(query, options) unless query.is_a?(Geocoder2::Query)
+    query.blank? ? [] : query.execute
+  end
+
+  ##
+  # Look up the coordinates of the given street or IP address.
+  #
+  def coordinates(address, options = {})
+    if (results = search(address, options)).size > 0
+      results.first.coordinates
+    end
+  end
+
+  ##
+  # Look up the address of the given coordinates ([lat,lon])
+  # or IP address (string).
+  #
+  def address(query, options = {})
+    if (results = search(query, options)).size > 0
+      results.first.address
+    end
+  end
+
+  ##
+  # The working Cache object, or +nil+ if none configured.
+  #
+  def cache
+    warn "WARNING: Calling Geocoder2.cache is DEPRECATED. The #cache method now belongs to the Geocoder2::Lookup object."
+    Geocoder2::Lookup.get(Geocoder2.config.lookup).cache
+  end
+end
+
+# load Railtie if Rails exists
+if defined?(Rails)
+  require "geocoder2/railtie"
+  Geocoder2::Railtie.insert
+end