geocoder2 0.1.0

data/lib/geocoder2/calculations.rb

@@ -0,0 +1,389 @@
+module Geocoder2
+  module Calculations
+    extend self
+
+    ##
+    # Compass point names, listed clockwise starting at North.
+    #
+    # If you want bearings named using more, fewer, or different points
+    # override Geocoder2::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
+
+    ##
+    # Conversion factor: multiply by nautical miles to get miles.
+    #
+    KM_IN_NM = 0.539957
+
+    # Not a number constant
+    NAN = defined?(::Float::NAN) ? ::Float::NAN : 0 / 0.0
+
+    ##
+    # Returns true if all given arguments are valid latitude/longitude values.
+    #
+    def coordinates_present?(*args)
+      args.each do |a|
+        # note that Float::NAN != Float::NAN
+        # still, this could probably be improved:
+        return false if (!a.is_a?(Numeric) or a.to_s == "NaN")
+      end
+      true
+    end
+
+    ##
+    # Distance spanned by one degree of latitude in the given units.
+    #
+    def latitude_degree_distance(units = nil)
+      units ||= Geocoder2.config.units
+      2 * Math::PI * earth_radius(units) / 360
+    end
+
+    ##
+    # 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 = nil)
+      units ||= Geocoder2.config.units
+      latitude_degree_distance(units) * Math.cos(to_radians(latitude))
+    end
+
+    ##
+    # Distance between two points on Earth (Haversine formula).
+    # Takes two points and an options hash.
+    # The points are given in the same way that points are given to all
+    # Geocoder2 methods that accept points as arguments. They can be:
+    #
+    # * an array of coordinates ([lat,lon])
+    # * a geocodable address (string)
+    # * a geocoded object (one which implements a +to_coordinates+ method
+    #   which returns a [lat,lon] array
+    #
+    # The options hash supports:
+    #
+    # * <tt>:units</tt> - <tt>:mi</tt> or <tt>:km</tt>
+    #   Use Geocoder2.configure(:units => ...) to configure default units.
+    #
+    def distance_between(point1, point2, options = {})
+
+      # set default options
+      options[:units] ||= Geocoder2.config.units
+
+      # convert to coordinate arrays
+      point1 = extract_coordinates(point1)
+      point2 = extract_coordinates(point2)
+
+      # convert degrees to radians
+      point1 = to_radians(point1)
+      point2 = to_radians(point2)
+
+      # compute deltas
+      dlat = point2[0] - point1[0]
+      dlon = point2[1] - point1[1]
+
+      a = (Math.sin(dlat / 2))**2 + Math.cos(point1[0]) *
+          (Math.sin(dlon / 2))**2 * Math.cos(point2[0])
+      c = 2 * Math.atan2( Math.sqrt(a), Math.sqrt(1-a))
+      c * earth_radius(options[:units])
+    end
+
+    ##
+    # Bearing between two points on Earth.
+    # Returns a number of degrees from due north (clockwise).
+    #
+    # See Geocoder2::Calculations.distance_between for
+    # ways of specifying the points. Also accepts an options hash:
+    #
+    # * <tt>:method</tt> - <tt>:linear</tt> 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 less confusing
+    #   (returns due east or west when given two points with the same latitude).
+    #   Use Geocoder2.configure(:distances => ...) to configure calculation method.
+    #
+    # Based on: http://www.movable-type.co.uk/scripts/latlong.html
+    #
+    def bearing_between(point1, point2, options = {})
+
+      # set default options
+      options[:method] ||= Geocoder2.config.distances
+      options[:method] = :linear unless options[:method] == :spherical
+
+      # convert to coordinate arrays
+      point1 = extract_coordinates(point1)
+      point2 = extract_coordinates(point2)
+
+      # convert degrees to radians
+      point1 = to_radians(point1)
+      point2 = to_radians(point2)
+
+      # compute deltas
+      dlat = point2[0] - point1[0]
+      dlon = point2[1] - point1[1]
+
+      case options[:method]
+      when :linear
+        y = dlon
+        x = dlat
+
+      when :spherical
+        y = Math.sin(dlon) * Math.cos(point2[0])
+        x = Math.cos(point1[0]) * Math.sin(point2[0]) -
+            Math.sin(point1[0]) * Math.cos(point2[0]) * 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
+
+    ##
+    # 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 convert degrees to radians
+      coords = points.map{ |p| to_radians(extract_coordinates(p)) }
+
+      # convert to Cartesian coordinates
+      x = []; y = []; z = []
+      coords.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, lon]
+    end
+
+    ##
+    # Returns coordinates of the southwest and northeast 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).
+    #
+    # See Geocoder2::Calculations.distance_between for
+    # ways of specifying the point. Also accepts an options hash:
+    #
+    # * <tt>:units</tt> - <tt>:mi</tt> or <tt>:km</tt>.
+    #   Use Geocoder2.configure(:units => ...) to configure default units.
+    #
+    def bounding_box(point, radius, options = {})
+      lat,lon = extract_coordinates(point)
+      radius  = radius.to_f
+      units   = options[:units] || Geocoder2.config.units
+      [
+        lat - (radius / latitude_degree_distance(units)),
+        lon - (radius / longitude_degree_distance(lat, units)),
+        lat + (radius / latitude_degree_distance(units)),
+        lon + (radius / longitude_degree_distance(lat, units))
+      ]
+    end
+
+    ##
+    # Random point within a circle of provided radius centered
+    # around the provided point
+    # Takes one point, one radius, and an options hash.
+    # The points are given in the same way that points are given to all
+    # Geocoder2 methods that accept points as arguments. They can be:
+    #
+    # * an array of coordinates ([lat,lon])
+    # * a geocodable address (string)
+    # * a geocoded object (one which implements a +to_coordinates+ method
+    #   which returns a [lat,lon] array
+    #
+    # The options hash supports:
+    #
+    # * <tt>:units</tt> - <tt>:mi</tt> or <tt>:km</tt>
+    #   Use Geocoder2.configure(:units => ...) to configure default units.
+    def random_point_near(center, radius, options = {})
+
+      # set default options
+      options[:units] ||= Geocoder2.config.units
+
+      # convert to coordinate arrays
+      center = extract_coordinates(center)
+
+      earth_circumference = 2 * Math::PI * earth_radius(options[:units])
+      max_degree_delta =  360.0 * (radius / earth_circumference)
+
+      # random bearing in radians
+      theta = 2 * Math::PI * rand
+
+      # random radius, use the square root to ensure a uniform
+      # distribution of points over the circle
+      r = Math.sqrt(rand) * max_degree_delta
+
+      delta_lat, delta_long = [r * Math.cos(theta), r * Math.sin(theta)]
+      [center[0] + delta_lat, center[1] + delta_long]
+    end
+
+    ##
+    # Convert degrees to radians.
+    # If an array (or multiple arguments) is passed,
+    # converts each value and returns array.
+    #
+    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
+
+    def distance_to_radians(distance, units = nil)
+      units ||= Geocoder2.config.units
+      distance.to_f / earth_radius(units)
+    end
+
+    def radians_to_distance(radians, units = nil)
+      units ||= Geocoder2.config.units
+      radians * earth_radius(units)
+    end
+
+    ##
+    # Convert miles to kilometers.
+    #
+    def to_kilometers(mi)
+      mi * mi_in_km
+    end
+
+    ##
+    # Convert kilometers to miles.
+    #
+    def to_miles(km)
+      km * km_in_mi
+    end
+
+    ##
+    # Convert kilometers to nautical miles.
+    #
+    def to_nautical_miles(km)
+      km * km_in_nm
+    end
+
+    ##
+    # Radius of the Earth in the given units (:mi or :km).
+    # Use Geocoder2.configure(:units => ...) to configure default units.
+    #
+    def earth_radius(units = nil)
+      units ||= Geocoder2.config.units
+      case units
+        when :km; EARTH_RADIUS
+        when :mi; to_miles(EARTH_RADIUS)
+        when :nm; to_nautical_miles(EARTH_RADIUS)
+      end
+    end
+
+    ##
+    # Conversion factor: km to mi.
+    #
+    def km_in_mi
+      KM_IN_MI
+    end
+
+    ##
+    # Conversion factor: km to nm.
+    #
+    def km_in_nm
+      KM_IN_NM
+    end
+
+
+
+    ##
+    # Conversion factor: mi to km.
+    #
+    def mi_in_km
+      1.0 / KM_IN_MI
+    end
+
+    ##
+    # Conversion factor: nm to km.
+    #
+    def nm_in_km
+      1.0 / KM_IN_NM
+    end
+
+    ##
+    # Takes an object which is a [lat,lon] array, a geocodable string,
+    # or an object that implements +to_coordinates+ and returns a
+    # [lat,lon] array. Note that if a string is passed this may be a slow-
+    # running method and may return nil.
+    #
+    def extract_coordinates(point)
+      case point
+      when Array
+        if point.size == 2
+          lat, lon = point
+          if !lat.nil? && lat.respond_to?(:to_f) and
+            !lon.nil? && lon.respond_to?(:to_f)
+          then
+            return [ lat.to_f, lon.to_f ]
+          end
+        end
+      when String
+        point = Geocoder2.coordinates(point) and return point
+      else
+        if point.respond_to?(:to_coordinates)
+          if Array === array = point.to_coordinates
+            return extract_coordinates(array)
+          end
+        end
+      end
+      [ NAN, NAN ]
+    end
+  end
+end
+

data/lib/geocoder2/cli.rb

@@ -0,0 +1,121 @@
+require 'geocoder2'
+require 'optparse'
+
+module Geocoder2
+  class Cli
+
+    def self.run(args, out = STDOUT)
+      show_url  = false
+      show_json = false
+
+      # remove arguments that are probably coordinates so they are not
+      # processed as arguments (eg: -31.96047031,115.84274631)
+      coords = args.select{ |i| i.match(/^-\d/) }
+      args -= coords
+
+      OptionParser.new{ |opts|
+        opts.banner = "Usage:\n    geocode [options] <location>"
+        opts.separator "\nOptions: "
+
+        opts.on("-k <key>", "--key <key>",
+          "Key for geocoding API (usually optional). Enclose multi-part keys in quotes and separate parts by spaces") do |key|
+          if (key_parts = key.split(/\s+/)).size > 1
+            Geocoder2.configure(:api_key => key_parts)
+          else
+            Geocoder2.configure(:api_key => key)
+          end
+        end
+
+        opts.on("-l <language>", "--language <language>",
+          "Language of output (see API docs for valid choices)") do |language|
+          Geocoder2.configure(:language => language)
+        end
+
+        opts.on("-p <proxy>", "--proxy <proxy>",
+          "HTTP proxy server to use (user:pass@host:port)") do |proxy|
+          Geocoder2.configure(:http_proxy => proxy)
+        end
+
+        opts.on("-s <service>", Geocoder2::Lookup.all_services_except_test, "--service <service>",
+          "Geocoding service: #{Geocoder2::Lookup.all_services_except_test * ', '}") do |service|
+          Geocoder2.configure(:lookup => service.to_sym)
+          Geocoder2.configure(:ip_lookup => service.to_sym)
+        end
+
+        opts.on("-t <seconds>", "--timeout <seconds>",
+          "Maximum number of seconds to wait for API response") do |timeout|
+          Geocoder2.configure(:timeout => timeout.to_i)
+        end
+
+        opts.on("-j", "--json", "Print API's raw JSON response") do
+          show_json = true
+        end
+
+        opts.on("-u", "--url", "Print URL for API query instead of result") do
+          show_url = true
+        end
+
+        opts.on_tail("-v", "--version", "Print version number") do
+          require "geocoder2/version"
+          out << "Geocoder2 #{Geocoder2::VERSION}\n"
+          exit
+        end
+
+        opts.on_tail("-h", "--help", "Print this help") do
+          out << "Look up geographic information about a location.\n\n"
+          out << opts
+          out << "\nCreated and maintained by Alex Reisner, available under the MIT License.\n"
+          out << "Report bugs and contribute at http://github.com/alexreisner/geocoder2\n"
+          exit
+        end
+      }.parse!(args)
+
+      # concatenate args with coords that might have been removed
+      # before option processing
+      query = (args + coords).join(" ")
+
+      if query == ""
+        out << "Please specify a location (run `geocode -h` for more info).\n"
+        exit 1
+      end
+
+      if show_url and show_json
+        out << "You can only specify one of -j and -u.\n"
+        exit 2
+      end
+
+      if show_url
+        q = Geocoder2::Query.new(query)
+        out << q.url + "\n"
+        exit 0
+      end
+
+      if show_json
+        q = Geocoder2::Query.new(query)
+        out << q.lookup.send(:fetch_raw_data, q) + "\n"
+        exit 0
+      end
+
+      if (result = Geocoder2.search(query).first)
+        google = Geocoder2::Lookup.get(:google)
+        lines = [
+          ["Latitude",       result.latitude],
+          ["Longitude",      result.longitude],
+          ["Full address",   result.address],
+          ["City",           result.city],
+          ["State/province", result.state],
+          ["Postal code",    result.postal_code],
+          ["Country",        result.country],
+          ["Google map",     google.map_link_url(result.coordinates)],
+        ]
+        lines.each do |line|
+          out << (line[0] + ": ").ljust(18) + line[1].to_s + "\n"
+        end
+        exit 0
+      else
+        out << "Location '#{query}' not found.\n"
+        exit 1
+      end
+    end
+  end
+end

data/lib/geocoder2/configuration.rb

@@ -0,0 +1,130 @@
+require 'singleton'
+require 'geocoder2/configuration_hash'
+
+module Geocoder2
+
+  ##
+  # Configuration options should be set by passing a hash:
+  #
+  #   Geocoder2.configure(
+  #     :timeout  => 5,
+  #     :lookup   => :yandex,
+  #     :api_key  => "2a9fsa983jaslfj982fjasd",
+  #     :units    => :km
+  #   )
+  #
+  def self.configure(options = nil, &block)
+    if block_given?
+      warn "WARNING: Passing a block to Geocoder2.configure is DEPRECATED. Please pass a hash instead (eg: Geocoder2.configure(:units => ..., :api_key => ...))."
+      block.call(Configuration.instance)
+    elsif !options.nil?
+      Configuration.instance.configure(options)
+    else
+      warn "WARNING: Use of Geocoder2.configure to read or write single config options is DEPRECATED. To write to the config please pass a hash (eg: Geocoder2.configure(:units => ...)). To read config options please use the Geocoder2.config object (eg: Geocoder2.config.units)."
+      Configuration.instance
+    end
+  end
+
+  ##
+  # Read-only access to the singleton's config data.
+  #
+  def self.config
+    Configuration.instance.data
+  end
+
+  ##
+  # Read-only access to lookup-specific config data.
+  #
+  def self.config_for_lookup(lookup_name)
+    data = config.clone
+    data.reject!{ |key,value| !Configuration::OPTIONS.include?(key) }
+    if config.has_key?(lookup_name)
+      data.merge!(config[lookup_name])
+    end
+    data
+  end
+
+  class Configuration
+    include Singleton
+
+    OPTIONS = [
+      :timeout,
+      :lookup,
+      :ip_lookup,
+      :language,
+      :http_headers,
+      :use_https,
+      :http_proxy,
+      :https_proxy,
+      :api_key,
+      :cache,
+      :cache_prefix,
+      :always_raise,
+      :units,
+      :distances
+    ]
+
+    attr_accessor :data
+
+    def self.set_defaults
+      instance.set_defaults
+    end
+
+    OPTIONS.each do |o|
+      define_method o do
+        @data[o]
+      end
+      define_method "#{o}=" do |value|
+        @data[o] = value
+      end
+    end
+
+    def configure(options)
+      @data.rmerge!(options)
+    end
+
+    def initialize # :nodoc
+      @data = Geocoder2::ConfigurationHash.new
+      set_defaults
+    end
+
+    def set_defaults
+
+      # geocoding options
+      @data[:timeout]      = 3           # geocoding service timeout (secs)
+      @data[:lookup]       = :google     # name of street address geocoding service (symbol)
+      @data[:ip_lookup]    = :freegeoip  # name of IP address geocoding service (symbol)
+      @data[:language]     = :en         # ISO-639 language code
+      @data[:http_headers] = {}          # HTTP headers for lookup
+      @data[:use_https]    = false       # use HTTPS for lookup requests? (if supported)
+      @data[:http_proxy]   = nil         # HTTP proxy server (user:pass@host:port)
+      @data[:https_proxy]  = nil         # HTTPS proxy server (user:pass@host:port)
+      @data[:api_key]      = nil         # API key for geocoding service
+      @data[:cache]        = nil         # cache object (must respond to #[], #[]=, and #keys)
+      @data[:cache_prefix] = "geocoder2:" # prefix (string) to use for all cache keys
+
+      # exceptions that should not be rescued by default
+      # (if you want to implement custom error handling);
+      # supports SocketError and TimeoutError
+      @data[:always_raise] = []
+
+      # calculation options
+      @data[:units]     = :mi      # :mi or :km
+      @data[:distances] = :linear  # :linear or :spherical
+    end
+
+    instance_eval(OPTIONS.map do |option|
+      o = option.to_s
+      <<-EOS
+      def #{o}
+        instance.data[:#{o}]
+      end
+
+      def #{o}=(value)
+        instance.data[:#{o}] = value
+      end
+      EOS
+    end.join("\n\n"))
+
+  end
+end

data/lib/geocoder2/configuration_hash.rb

@@ -0,0 +1,11 @@
+require 'hash_recursive_merge'
+
+module Geocoder2
+  class ConfigurationHash < Hash
+    include HashRecursiveMerge
+
+    def method_missing(meth, *args, &block)
+      has_key?(meth) ? self[meth] : super
+    end
+  end
+end

data/lib/geocoder2/exceptions.rb

@@ -0,0 +1,21 @@
+module Geocoder2
+
+  class Error < StandardError
+  end
+
+  class ConfigurationError < Error
+  end
+
+  class OverQueryLimitError < Error
+  end
+
+  class RequestDenied < Error
+  end
+
+  class InvalidRequest < Error
+  end
+
+  class InvalidApiKey < Error
+  end
+
+end