geocoder 1.1.9 → 1.8.0

data/lib/geocoder/calculations.rb

@@ -10,12 +10,6 @@ module Geocoder
     #
     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.
     #
@@ -26,6 +20,21 @@ module Geocoder
     #
     KM_IN_NM = 0.539957
 
+    ##
+    # Conversion factor: multiply by radians to get degrees.
+    #
+    DEGREES_PER_RADIAN = 57.2957795
+
+    ##
+    # Radius of the Earth, in kilometers.
+    # Value taken from: http://en.wikipedia.org/wiki/Earth_radius
+    #
+    EARTH_RADII = {km: 6371.0}
+    EARTH_RADII[:mi] = EARTH_RADII[:km] * KM_IN_MI
+    EARTH_RADII[:nm] = EARTH_RADII[:km] * KM_IN_NM
+
+    EARTH_RADIUS = EARTH_RADII[:km] # TODO: deprecate this constant (use `EARTH_RADII[:km]`)
+
     # Not a number constant
     NAN = defined?(::Float::NAN) ? ::Float::NAN : 0 / 0.0
 
@@ -45,7 +54,6 @@ module Geocoder
     # Distance spanned by one degree of latitude in the given units.
     #
     def latitude_degree_distance(units = nil)
-      units ||= Geocoder.config.units
       2 * Math::PI * earth_radius(units) / 360
     end
 
@@ -54,7 +62,6 @@ module Geocoder
     # This ranges from around 69 miles at the equator to zero at the poles.
     #
     def longitude_degree_distance(latitude, units = nil)
-      units ||= Geocoder.config.units
       latitude_degree_distance(units) * Math.cos(to_radians(latitude))
     end
 
@@ -75,10 +82,6 @@ module Geocoder
     #   Use Geocoder.configure(:units => ...) to configure default units.
     #
     def distance_between(point1, point2, options = {})
-
-      # set default options
-      options[:units] ||= Geocoder.config.units
-
       # convert to coordinate arrays
       point1 = extract_coordinates(point1)
       point2 = extract_coordinates(point2)
@@ -151,7 +154,7 @@ module Geocoder
     # Translate a bearing (float) into a compass direction (string, eg "North").
     #
     def compass_point(bearing, points = COMPASS_POINTS)
-      seg_size = 360 / points.size
+      seg_size = 360.0 / points.size
       points[((bearing + (seg_size / 2)) % 360) / seg_size]
     end
 
@@ -207,12 +210,11 @@ module Geocoder
     def bounding_box(point, radius, options = {})
       lat,lon = extract_coordinates(point)
       radius  = radius.to_f
-      units   = options[:units] || Geocoder.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))
+        lat - (radius / latitude_degree_distance(options[:units])),
+        lon - (radius / longitude_degree_distance(lat, options[:units])),
+        lat + (radius / latitude_degree_distance(options[:units])),
+        lon + (radius / longitude_degree_distance(lat, options[:units]))
       ]
     end
 
@@ -232,10 +234,9 @@ module Geocoder
     #
     # * <tt>:units</tt> - <tt>:mi</tt> or <tt>:km</tt>
     #   Use Geocoder.configure(:units => ...) to configure default units.
+    # * <tt>:seed</tt> - The seed for the random number generator
     def random_point_near(center, radius, options = {})
-
-      # set default options
-      options[:units] ||= Geocoder.config.units
+      random = Random.new(options[:seed] || Random.new_seed)
 
       # convert to coordinate arrays
       center = extract_coordinates(center)
@@ -244,16 +245,49 @@ module Geocoder
       max_degree_delta =  360.0 * (radius / earth_circumference)
 
       # random bearing in radians
-      theta = 2 * Math::PI * rand
+      theta = 2 * Math::PI * random.rand
 
       # random radius, use the square root to ensure a uniform
       # distribution of points over the circle
-      r = Math.sqrt(rand) * max_degree_delta
+      r = Math.sqrt(random.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
 
+    ##
+    # Given a start point, heading (in degrees), and distance, provides
+    # an endpoint.
+    # The starting point is given in the same way that points are given to all
+    # Geocoder methods that accept points as arguments. It 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
+    #
+    def endpoint(start, heading, distance, options = {})
+      radius = earth_radius(options[:units])
+
+      start = extract_coordinates(start)
+
+      # convert degrees to radians
+      start = to_radians(start)
+
+      lat = start[0]
+      lon = start[1]
+      heading = to_radians(heading)
+      distance = distance.to_f
+
+      end_lat = Math.asin(Math.sin(lat)*Math.cos(distance/radius) +
+                    Math.cos(lat)*Math.sin(distance/radius)*Math.cos(heading))
+
+      end_lon = lon+Math.atan2(Math.sin(heading)*Math.sin(distance/radius)*Math.cos(lat),
+                    Math.cos(distance/radius)-Math.sin(lat)*Math.sin(end_lat))
+
+      to_degrees [end_lat, end_lon]
+    end
+
     ##
     # Convert degrees to radians.
     # If an array (or multiple arguments) is passed,
@@ -283,12 +317,10 @@ module Geocoder
     end
 
     def distance_to_radians(distance, units = nil)
-      units ||= Geocoder.config.units
       distance.to_f / earth_radius(units)
     end
 
     def radians_to_distance(radians, units = nil)
-      units ||= Geocoder.config.units
       radians * earth_radius(units)
     end
 
@@ -296,6 +328,7 @@ module Geocoder
     # Convert miles to kilometers.
     #
     def to_kilometers(mi)
+      Geocoder.log(:warn, "DEPRECATION WARNING: Geocoder::Calculations.to_kilometers is deprecated and will be removed in Geocoder 1.5.0. Please multiply by MI_IN_KM instead.")
       mi * mi_in_km
     end
 
@@ -303,14 +336,16 @@ module Geocoder
     # Convert kilometers to miles.
     #
     def to_miles(km)
-      km * km_in_mi
+      Geocoder.log(:warn, "DEPRECATION WARNING: Geocoder::Calculations.to_miles is deprecated and will be removed in Geocoder 1.5.0. Please multiply by KM_IN_MI instead.")
+      km * KM_IN_MI
     end
 
     ##
     # Convert kilometers to nautical miles.
     #
     def to_nautical_miles(km)
-      km * km_in_nm
+      Geocoder.log(:warn, "DEPRECATION WARNING: Geocoder::Calculations.to_nautical_miles is deprecated and will be removed in Geocoder 1.5.0. Please multiply by KM_IN_NM instead.")
+      km * KM_IN_NM
     end
 
     ##
@@ -318,18 +353,14 @@ module Geocoder
     # Use Geocoder.configure(:units => ...) to configure default units.
     #
     def earth_radius(units = nil)
-      units ||= Geocoder.config.units
-      case units
-        when :km; EARTH_RADIUS
-        when :mi; to_miles(EARTH_RADIUS)
-        when :nm; to_nautical_miles(EARTH_RADIUS)
-      end
+      EARTH_RADII[units || Geocoder.config.units]
     end
 
     ##
     # Conversion factor: km to mi.
     #
     def km_in_mi
+      Geocoder.log(:warn, "DEPRECATION WARNING: Geocoder::Calculations.km_in_mi is deprecated and will be removed in Geocoder 1.5.0. Please use the constant KM_IN_MI instead.")
       KM_IN_MI
     end
 
@@ -337,15 +368,15 @@ module Geocoder
     # Conversion factor: km to nm.
     #
     def km_in_nm
+      Geocoder.log(:warn, "DEPRECATION WARNING: Geocoder::Calculations.km_in_nm is deprecated and will be removed in Geocoder 1.5.0. Please use the constant KM_IN_NM instead.")
       KM_IN_NM
     end
 
-
-
     ##
     # Conversion factor: mi to km.
     #
     def mi_in_km
+      Geocoder.log(:warn, "DEPRECATION WARNING: Geocoder::Calculations.mi_in_km is deprecated and will be removed in Geocoder 1.5.0. Please use 1.0 / KM_IN_MI instead.")
       1.0 / KM_IN_MI
     end
 
@@ -353,6 +384,7 @@ module Geocoder
     # Conversion factor: nm to km.
     #
     def nm_in_km
+      Geocoder.log(:warn, "DEPRECATION WARNING: Geocoder::Calculations.nm_in_km is deprecated and will be removed in Geocoder 1.5.0. Please use 1.0 / KM_IN_NM instead.")
       1.0 / KM_IN_NM
     end
 
@@ -386,4 +418,3 @@ module Geocoder
     end
   end
 end
-

data/lib/geocoder/cli.rb

@@ -97,7 +97,7 @@ module Geocoder
       end
 
       if (result = Geocoder.search(query).first)
-        google = Geocoder::Lookup.get(:google)
+        nominatim = Geocoder::Lookup.get(:nominatim)
         lines = [
           ["Latitude",       result.latitude],
           ["Longitude",      result.longitude],
@@ -106,7 +106,7 @@ module Geocoder
           ["State/province", result.state],
           ["Postal code",    result.postal_code],
           ["Country",        result.country],
-          ["Google map",     google.map_link_url(result.coordinates)],
+          ["Map",            nominatim.map_link_url(result.coordinates)],
         ]
         lines.each do |line|
           out << (line[0] + ": ").ljust(18) + line[1].to_s + "\n"

data/lib/geocoder/configuration.rb

@@ -1,5 +1,6 @@
 require 'singleton'
 require 'geocoder/configuration_hash'
+require 'geocoder/util'
 
 module Geocoder
 
@@ -14,14 +15,8 @@ module Geocoder
   #   )
   #
   def self.configure(options = nil, &block)
-    if block_given?
-      warn "WARNING: Passing a block to Geocoder.configure is DEPRECATED. Please pass a hash instead (eg: Geocoder.configure(:units => ..., :api_key => ...))."
-      block.call(Configuration.instance)
-    elsif !options.nil?
+    if !options.nil?
       Configuration.instance.configure(options)
-    else
-      warn "WARNING: Use of Geocoder.configure to read or write single config options is DEPRECATED. To write to the config please pass a hash (eg: Geocoder.configure(:units => ...)). To read config options please use the Geocoder.config object (eg: Geocoder.config.units)."
-      Configuration.instance
     end
   end
 
@@ -44,6 +39,14 @@ module Geocoder
     data
   end
 
+  ##
+  # Merge the given hash into a lookup's existing configuration.
+  #
+  def self.merge_into_lookup_config(lookup_name, options)
+    base = Geocoder.config[lookup_name]
+    Geocoder.configure(lookup_name => base.merge(options))
+  end
+
   class Configuration
     include Singleton
 
@@ -52,16 +55,20 @@ module Geocoder
       :lookup,
       :ip_lookup,
       :language,
+      :host,
       :http_headers,
       :use_https,
       :http_proxy,
       :https_proxy,
       :api_key,
       :cache,
-      :cache_prefix,
       :always_raise,
       :units,
-      :distances
+      :distances,
+      :basic_auth,
+      :logger,
+      :kernel_logger_level,
+      :cache_options
     ]
 
     attr_accessor :data
@@ -80,7 +87,7 @@ module Geocoder
     end
 
     def configure(options)
-      @data.rmerge!(options)
+      Util.recursive_hash_merge(@data, options)
     end
 
     def initialize # :nodoc
@@ -92,25 +99,36 @@ module Geocoder
 
       # 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[:lookup]       = :nominatim  # name of street address geocoding service (symbol)
+      @data[:ip_lookup]    = :ipinfo_io  # 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] = "geocoder:" # prefix (string) to use for all cache keys
+      @data[:basic_auth]   = {}          # user and password for basic auth ({:user => "user", :password => "password"})
+      @data[:logger]       = :kernel     # :kernel or Logger instance
+      @data[:kernel_logger_level] = ::Logger::WARN # log level, if kernel logger is used
 
       # exceptions that should not be rescued by default
       # (if you want to implement custom error handling);
-      # supports SocketError and TimeoutError
+      # supports SocketError and Timeout::Error
       @data[:always_raise] = []
 
       # calculation options
       @data[:units]     = :mi      # :mi or :km
       @data[:distances] = :linear  # :linear or :spherical
+
+      # Set the default values for the caching mechanism
+      # By default, the cache keys will not expire as IP addresses and phyiscal
+      # addresses will rarely change.
+      @data[:cache]        = nil   # cache object (must respond to #[], #[]=, and optionally #keys)
+      @data[:cache_prefix] = nil   # - DEPRECATED - prefix (string) to use for all cache keys
+      @data[:cache_options] = {
+        prefix: 'geocoder:',
+        expiration: nil
+      }
     end
 
     instance_eval(OPTIONS.map do |option|
@@ -125,6 +143,5 @@ module Geocoder
       end
       EOS
     end.join("\n\n"))
-
   end
 end

data/lib/geocoder/configuration_hash.rb

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

data/lib/geocoder/esri_token.rb

@@ -0,0 +1,38 @@
+module Geocoder
+  class EsriToken
+    attr_accessor :value, :expires_at
+
+    def initialize(value, expires_at)
+      @value = value
+      @expires_at = expires_at
+    end
+
+    def to_s
+        @value
+    end
+
+    def active?
+      @expires_at > Time.now
+    end
+
+    def self.generate_token(client_id, client_secret, expires=1440)
+      # creates a new token that will expire in 1 day by default
+      getToken = Net::HTTP.post_form URI('https://www.arcgis.com/sharing/rest/oauth2/token'),
+        f: 'json',
+        client_id: client_id,
+        client_secret: client_secret,
+        grant_type: 'client_credentials',
+        expiration: expires # (minutes) max: 20160, default: 1 day
+
+      response = JSON.parse(getToken.body)
+
+      if response['error']
+        Geocoder.log(:warn, response['error'])
+      else
+        token_value = response['access_token']
+        expires_at = Time.now + (expires * 60)
+        new(token_value, expires_at)
+      end
+    end
+  end
+end

data/lib/geocoder/exceptions.rb

@@ -1,3 +1,5 @@
+require 'timeout'
+
 module Geocoder
 
   class Error < StandardError
@@ -9,6 +11,14 @@ module Geocoder
   class OverQueryLimitError < Error
   end
 
+  class ResponseParseError < Error
+    attr_reader :response
+
+    def initialize(response)
+      @response = response
+    end
+  end
+
   class RequestDenied < Error
   end
 
@@ -18,4 +28,13 @@ module Geocoder
   class InvalidApiKey < Error
   end
 
+  class ServiceUnavailable < Error
+  end
+
+  class LookupTimeout < ::Timeout::Error
+  end
+
+  class NetworkError < Error
+  end
+
 end

data/lib/geocoder/ip_address.rb

@@ -0,0 +1,33 @@
+require 'resolv'
+module Geocoder
+  class IpAddress < String
+    PRIVATE_IPS = [
+      '10.0.0.0/8',
+      '172.16.0.0/12',
+      '192.168.0.0/16',
+    ].map { |ip| IPAddr.new(ip) }.freeze
+
+    def initialize(ip)
+      ip = ip.to_string if ip.is_a?(IPAddr)
+
+      super(ip)
+    end
+
+    def internal?
+      loopback? || private?
+    end
+
+    def loopback?
+      valid? and !!(self == "0.0.0.0" or self.match(/\A127\./) or self == "::1")
+    end
+
+    def private?
+      valid? && PRIVATE_IPS.any? { |ip| ip.include?(self) }
+    end
+
+    def valid?
+      ip = self[/(?<=\[)(.*?)(?=\])/] || self
+      !!((ip =~ Resolv::IPv4::Regex) || (ip =~ Resolv::IPv6::Regex))
+    end
+  end
+end

data/lib/geocoder/kernel_logger.rb

@@ -0,0 +1,25 @@
+module Geocoder
+  class KernelLogger
+    include Singleton
+
+    def add(level, message)
+      return unless log_message_at_level?(level)
+      case level
+        when ::Logger::DEBUG, ::Logger::INFO
+          puts message
+        when ::Logger::WARN
+          warn message
+        when ::Logger::ERROR
+          raise message
+        when ::Logger::FATAL
+          fail message
+      end
+    end
+
+    private # ----------------------------------------------------------------
+
+    def log_message_at_level?(level)
+      level >= Geocoder.config.kernel_logger_level
+    end
+  end
+end

data/lib/geocoder/logger.rb

@@ -0,0 +1,47 @@
+require 'logger'
+
+module Geocoder
+
+  def self.log(level, message)
+    Logger.instance.log(level, message)
+  end
+
+  class Logger
+    include Singleton
+
+    SEVERITY = {
+      debug: ::Logger::DEBUG,
+      info: ::Logger::INFO,
+      warn: ::Logger::WARN,
+      error: ::Logger::ERROR,
+      fatal: ::Logger::FATAL
+    }
+
+    def log(level, message)
+      unless valid_level?(level)
+        raise StandardError, "Geocoder tried to log a message with an invalid log level."
+      end
+      if current_logger.respond_to? :add
+        current_logger.add(SEVERITY[level], message)
+      else
+        raise Geocoder::ConfigurationError, "Please specify valid logger for Geocoder. " +
+        "Logger specified must be :kernel or must respond to `add(level, message)`."
+      end
+      nil
+    end
+
+    private # ----------------------------------------------------------------
+
+    def current_logger
+      logger = Geocoder.config[:logger]
+      if logger == :kernel
+        logger = Geocoder::KernelLogger.instance
+      end
+      logger
+    end
+
+    def valid_level?(level)
+      SEVERITY.keys.include?(level)
+    end
+  end
+end

data/lib/geocoder/lookup.rb

@@ -1,3 +1,5 @@
+require "geocoder/lookups/test"
+
 module Geocoder
   module Lookup
     extend self
@@ -16,25 +18,55 @@ module Geocoder
       all_services - [:test]
     end
 
+    ##
+    # Array of valid Lookup service names, excluding any that do not build their own HTTP requests.
+    # For example, Amazon Location Service uses the AWS gem, not HTTP REST requests, to fetch data.
+    #
+    def all_services_with_http_requests
+      all_services_except_test - [:amazon_location_service]
+    end
+
     ##
     # All street address lookup services, default first.
     #
     def street_services
-      [
+      @street_services ||= [
+        :location_iq,
         :dstk,
         :esri,
         :google,
         :google_premier,
-        :yahoo,
+        :google_places_details,
+        :google_places_search,
         :bing,
         :geocoder_ca,
-        :geocoder_us,
         :yandex,
+        :nationaal_georegister_nl,
         :nominatim,
+        :mapbox,
         :mapquest,
-        :ovi,
+        :uk_ordnance_survey_names,
+        :opencagedata,
+        :pelias,
+        :pickpoint,
+        :here,
         :baidu,
-        :test
+        :tencent,
+        :geocodio,
+        :smarty_streets,
+        :postcode_anywhere_uk,
+        :postcodes_io,
+        :geoportail_lu,
+        :ban_data_gouv_fr,
+        :test,
+        :latlon,
+        :amap,
+        :osmnames,
+        :melissa_street,
+        :amazon_location_service,
+        :geoapify,
+        :photon,
+        :twogis
       ]
     end
 
@@ -42,9 +74,30 @@ module Geocoder
     # All IP address lookup services, default first.
     #
     def ip_services
-      [:freegeoip, :maxmind]
+      @ip_services ||= [
+        :baidu_ip,
+        :abstract_api,
+        :freegeoip,
+        :geoip2,
+        :maxmind,
+        :maxmind_local,
+        :telize,
+        :pointpin,
+        :maxmind_geoip2,
+        :ipinfo_io,
+        :ipregistry,
+        :ipapi_com,
+        :ipdata_co,
+        :db_ip_com,
+        :ipstack,
+        :ip2location,
+        :ipgeolocation,
+        :ipqualityscore
+      ]
     end
 
+    attr_writer :street_services, :ip_services
+
     ##
     # Retrieve a Lookup object from the store.
     # Use this instead of Geocoder::Lookup::X.new to get an
@@ -64,7 +117,8 @@ module Geocoder
     #
     def spawn(name)
       if all_services.include?(name)
-        Geocoder::Lookup.const_get(classify_name(name)).new
+        name = name.to_s
+        instantiate_lookup(name)
       else
         valids = all_services.map(&:inspect).join(", ")
         raise ConfigurationError, "Please specify a valid lookup for Geocoder " +
@@ -78,9 +132,18 @@ module Geocoder
     def classify_name(filename)
       filename.to_s.split("_").map{ |i| i[0...1].upcase + i[1..-1] }.join
     end
-  end
-end
 
-Geocoder::Lookup.all_services.each do |name|
-  require "geocoder/lookups/#{name}"
+    ##
+    # Safely instantiate Lookup
+    #
+    def instantiate_lookup(name)
+      class_name = "Geocoder::Lookup::#{classify_name(name)}"
+      begin
+        Geocoder::Lookup.const_get(class_name)
+      rescue NameError
+        require "geocoder/lookups/#{name}"
+      end
+      Geocoder::Lookup.const_get(class_name).new
+    end
+  end
 end