geocoder 1.1.4 → 1.1.8

data/lib/geocoder/calculations.rb

@@ -21,6 +21,11 @@ module Geocoder
     #
     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
 
@@ -40,7 +45,7 @@ module Geocoder
     # Distance spanned by one degree of latitude in the given units.
     #
     def latitude_degree_distance(units = nil)
-      units ||= Geocoder::Configuration.units
+      units ||= Geocoder.config.units
       2 * Math::PI * earth_radius(units) / 360
     end
 
@@ -49,7 +54,7 @@ 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::Configuration.units
+      units ||= Geocoder.config.units
       latitude_degree_distance(units) * Math.cos(to_radians(latitude))
     end
 
@@ -67,12 +72,12 @@ module Geocoder
     # The options hash supports:
     #
     # * <tt>:units</tt> - <tt>:mi</tt> or <tt>:km</tt>
-    #   See Geocoder::Configuration to know how configure default units.
+    #   Use Geocoder.configure(:units => ...) to configure default units.
     #
     def distance_between(point1, point2, options = {})
 
       # set default options
-      options[:units] ||= Geocoder::Configuration.units
+      options[:units] ||= Geocoder.config.units
 
       # convert to coordinate arrays
       point1 = extract_coordinates(point1)
@@ -103,14 +108,14 @@ module Geocoder
     #   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).
-    #   See Geocoder::Configuration to know how configure default method.
+    #   Use Geocoder.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] ||= Geocoder::Configuration.distances
+      options[:method] ||= Geocoder.config.distances
       options[:method] = :linear unless options[:method] == :spherical
 
       # convert to coordinate arrays
@@ -197,12 +202,12 @@ module Geocoder
     # ways of specifying the point. Also accepts an options hash:
     #
     # * <tt>:units</tt> - <tt>:mi</tt> or <tt>:km</tt>.
-    #   See Geocoder::Configuration to know how configure default units.
+    #   Use Geocoder.configure(:units => ...) to configure default units.
     #
     def bounding_box(point, radius, options = {})
       lat,lon = extract_coordinates(point)
       radius  = radius.to_f
-      units   = options[:units] || Geocoder::Configuration.units
+      units   = options[:units] || Geocoder.config.units
       [
         lat - (radius / latitude_degree_distance(units)),
         lon - (radius / longitude_degree_distance(lat, units)),
@@ -240,12 +245,12 @@ module Geocoder
     end
 
     def distance_to_radians(distance, units = nil)
-      units ||= Geocoder::Configuration.units
+      units ||= Geocoder.config.units
       distance.to_f / earth_radius(units)
     end
 
     def radians_to_distance(radians, units = nil)
-      units ||= Geocoder::Configuration.units
+      units ||= Geocoder.config.units
       radians * earth_radius(units)
     end
 
@@ -263,13 +268,24 @@ module Geocoder
       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).
-    # See Geocoder::Configuration to know how configure default units.
+    # Use Geocoder.configure(:units => ...) to configure default units.
     #
     def earth_radius(units = nil)
-      units ||= Geocoder::Configuration.units
-      units == :km ? EARTH_RADIUS : to_miles(EARTH_RADIUS)
+      units ||= Geocoder.config.units
+      case units
+        when :km; EARTH_RADIUS
+        when :mi; to_miles(EARTH_RADIUS)
+        when :nm; to_nautical_miles(EARTH_RADIUS)
+      end
     end
 
     ##
@@ -279,6 +295,15 @@ module Geocoder
       KM_IN_MI
     end
 
+    ##
+    # Conversion factor: km to nm.
+    #
+    def km_in_nm
+      KM_IN_NM
+    end
+
+
+
     ##
     # Conversion factor: mi to km.
     #
@@ -286,6 +311,13 @@ module Geocoder
       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

data/lib/geocoder/cli.rb

@@ -13,34 +13,33 @@ module Geocoder
         opts.separator "\nOptions: "
 
         opts.on("-k <key>", "--key <key>",
-          "Key for geocoding API (optional for most). For Google Premier use 'key client channel' separated by spaces") do |key|
-          premier_key = key.split(' ')
-          if premier_key.length == 3
-            Geocoder::Configuration.api_key = premier_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
+            Geocoder.configure(:api_key => key_parts)
           else
-            Geocoder::Configuration.api_key = key
+            Geocoder.configure(:api_key => key)
           end
         end
 
         opts.on("-l <language>", "--language <language>",
           "Language of output (see API docs for valid choices)") do |language|
-          Geocoder::Configuration.language = language
+          Geocoder.configure(:language => language)
         end
 
         opts.on("-p <proxy>", "--proxy <proxy>",
           "HTTP proxy server to use (user:pass@host:port)") do |proxy|
-          Geocoder::Configuration.http_proxy = proxy
+          Geocoder.configure(:http_proxy => proxy)
         end
 
         opts.on("-s <service>", Geocoder::Lookup.all_services_except_test, "--service <service>",
           "Geocoding service: #{Geocoder::Lookup.all_services_except_test * ', '}") do |service|
-          Geocoder::Configuration.lookup = service.to_sym
-          Geocoder::Configuration.ip_lookup = service.to_sym
+          Geocoder.configure(:lookup => service.to_sym)
+          Geocoder.configure(:ip_lookup => service.to_sym)
         end
 
         opts.on("-t <seconds>", "--timeout <seconds>",
           "Maximum number of seconds to wait for API response") do |timeout|
-          Geocoder::Configuration.timeout = timeout.to_i
+          Geocoder.configure(:timeout => timeout.to_i)
         end
 
         opts.on("-j", "--json", "Print API's raw JSON response") do
@@ -80,7 +79,7 @@ module Geocoder
 
       if show_url
         q = Geocoder::Query.new(query)
-        out << q.lookup.send(:query_url, q) + "\n"
+        out << q.url + "\n"
         exit 0
       end
 

data/lib/geocoder/configuration.rb

@@ -1,39 +1,49 @@
 require 'singleton'
+require 'geocoder/configuration_hash'
 
 module Geocoder
 
   ##
-  # Provides convenient access to the Configuration singleton.
+  # Configuration options should be set by passing a hash:
   #
-  def self.configure(&block)
+  #   Geocoder.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 Geocoder.configure is DEPRECATED. Please pass a hash instead (eg: Geocoder.configure(:units => ..., :api_key => ...))."
       block.call(Configuration.instance)
+    elsif !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
 
   ##
-  # This class handles geocoder Geocoder configuration
-  # (geocoding service provider, caching, units of measurement, etc).
-  # Configuration can be done in two ways:
-  #
-  # 1) Using Geocoder.configure and passing a block
-  #    (useful for configuring multiple things at once):
-  #
-  #   Geocoder.configure do |config|
-  #     config.timeout      = 5
-  #     config.lookup       = :yahoo
-  #     config.api_key      = "2a9fsa983jaslfj982fjasd"
-  #     config.units        = :km
-  #   end
+  # Read-only access to the singleton's config data.
   #
-  # 2) Using the Geocoder::Configuration singleton directly:
-  #
-  #   Geocoder::Configuration.language = 'pt-BR'
-  #
-  # Default values are defined in Configuration#set_defaults.
+  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
 
@@ -54,53 +64,67 @@ module Geocoder
       :distances
     ]
 
-    attr_accessor *OPTIONS
+    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 = Geocoder::ConfigurationHash.new
       set_defaults
     end
 
     def set_defaults
-      @timeout      = 3           # geocoding service timeout (secs)
-      @lookup       = :google     # name of street address geocoding service (symbol)
-      @ip_lookup    = :freegeoip  # name of IP address geocoding service (symbol)
-      @language     = :en         # ISO-639 language code
-      @http_headers = {}          # HTTP headers for lookup
-      @use_https    = false       # use HTTPS for lookup requests? (if supported)
-      @http_proxy   = nil         # HTTP proxy server (user:pass@host:port)
-      @https_proxy  = nil         # HTTPS proxy server (user:pass@host:port)
-      @api_key      = nil         # API key for geocoding service
-      @cache        = nil         # cache object (must respond to #[], #[]=, and #keys)
-      @cache_prefix = "geocoder:" # prefix (string) to use for all cache keys
+
+      # 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] = "geocoder:" # 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
-      @always_raise = []
+      @data[:always_raise] = []
 
       # calculation options
-      @units     = :mi     # :mi or :km
-      @distances = :linear # :linear or :spherical
+      @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.#{o}
+        instance.data[:#{o}]
       end
 
       def #{o}=(value)
-        instance.#{o} = value
+        instance.data[:#{o}] = value
       end
       EOS
     end.join("\n\n"))
 
-    class << self
-      def set_defaults
-        instance.set_defaults
-      end
-    end
-
   end
 end

data/lib/geocoder/configuration_hash.rb

@@ -0,0 +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
+  end
+end

data/lib/geocoder/exceptions.rb

@@ -15,4 +15,7 @@ module Geocoder
   class InvalidRequest < Error
   end
 
+  class InvalidApiKey < Error
+  end
+
 end

data/lib/geocoder/lookup.rb

@@ -21,6 +21,7 @@ module Geocoder
     #
     def street_services
       [
+        :esri,
         :google,
         :google_premier,
         :yahoo,
@@ -29,6 +30,7 @@ module Geocoder
         :yandex,
         :nominatim,
         :mapquest,
+        :ovi,
         :test
       ]
     end
@@ -37,7 +39,7 @@ module Geocoder
     # All IP address lookup services, default first.
     #
     def ip_services
-      [:freegeoip]
+      [:freegeoip, :maxmind]
     end
 
     ##

data/lib/geocoder/lookups/base.rb

@@ -16,6 +16,21 @@ module Geocoder
 
     class Base
 
+      ##
+      # Human-readable name of the geocoding API.
+      #
+      def name
+        fail
+      end
+
+      ##
+      # Symbol which is used in configuration to refer to this Lookup.
+      #
+      def handle
+        str = self.class.to_s
+        str[str.rindex(':')+1..-1].gsub(/([a-z\d]+)([A-Z])/,'\1_\2').downcase.to_sym
+      end
+
       ##
       # Query the geocoding API and return a Geocoder::Result object.
       # Returns +nil+ on timeout or error.
@@ -43,16 +58,47 @@ module Geocoder
         nil
       end
 
+      ##
+      # Array containing string descriptions of keys required by the API.
+      # Empty array if keys are optional or not required.
+      #
+      def required_api_key_parts
+        []
+      end
+
+      ##
+      # URL to use for querying the geocoding engine.
+      #
+      def query_url(query)
+        fail
+      end
+      
+      ##
+      # The working Cache object.
+      #
+      def cache
+        if @cache.nil? and store = configuration.cache
+          @cache = Cache.new(store, configuration.cache_prefix)
+        end
+        @cache
+      end
 
       private # -------------------------------------------------------------
 
+      ##
+      # An object with configuration data for this particular lookup.
+      #
+      def configuration
+        Geocoder.config_for_lookup(handle)
+      end
+
       ##
       # Object used to make HTTP requests.
       #
       def http_client
-        protocol = "http#{'s' if Geocoder::Configuration.use_https}"
+        protocol = "http#{'s' if configuration.use_https}"
         proxy_name = "#{protocol}_proxy"
-        if proxy = Geocoder::Configuration.send(proxy_name)
+        if proxy = configuration.send(proxy_name)
           proxy_url = protocol + '://' + proxy
           begin
             uri = URI.parse(proxy_url)
@@ -84,10 +130,13 @@ module Geocoder
       end
 
       ##
-      # URL to use for querying the geocoding engine.
+      # Key to use for caching a geocoding result. Usually this will be the
+      # request URL, but in cases where OAuth is used and the nonce,
+      # timestamp, etc varies from one request to another, we need to use
+      # something else (like the URL before OAuth encoding).
       #
-      def query_url(query)
-        fail
+      def cache_key(query)
+        query_url(query)
       end
 
       ##
@@ -102,7 +151,7 @@ module Geocoder
       # Return false if exception not raised.
       #
       def raise_error(error, message = nil)
-        exceptions = Geocoder::Configuration.always_raise
+        exceptions = configuration.always_raise
         if exceptions == :all or exceptions.include?( error.is_a?(Class) ? error : error.class )
           raise error, message
         else
@@ -119,7 +168,7 @@ module Geocoder
         raise_error(err) or warn "Geocoding API connection cannot be established."
       rescue TimeoutError => err
         raise_error(err) or warn "Geocoding API not responding fast enough " +
-          "(see Geocoder::Configuration.timeout to set limit)."
+          "(use Geocoder.configure(:timeout => ...) to set limit)."
       end
 
       ##
@@ -140,37 +189,50 @@ module Geocoder
       # Set in configuration but not available for every service.
       #
       def protocol
-        "http" + (Geocoder::Configuration.use_https ? "s" : "")
+        "http" + (configuration.use_https ? "s" : "")
       end
 
       ##
-      # Fetches a raw search result (JSON string).
+      # Fetch a raw geocoding result (JSON string).
+      # The result might or might not be cached.
       #
       def fetch_raw_data(query)
-        timeout(Geocoder::Configuration.timeout) do
-          url = query_url(query)
-          uri = URI.parse(url)
-          if cache and body = cache[url]
-            @cache_hit = true
-          else
-            client = http_client.new(uri.host, uri.port)
-            client.use_ssl = true if Geocoder::Configuration.use_https
-            response = client.get(uri.request_uri, Geocoder::Configuration.http_headers)
-            body = response.body
-            if cache and (200..399).include?(response.code.to_i)
-              cache[url] = body
-            end
-            @cache_hit = false
+        key = cache_key(query)
+        if cache and body = cache[key]
+          @cache_hit = true
+        else
+          check_api_key_configuration!(query)
+          response = make_api_request(query)
+          body = response.body
+          if cache and (200..399).include?(response.code.to_i)
+            cache[key] = body
           end
-          body
+          @cache_hit = false
         end
+        body
       end
 
       ##
-      # The working Cache object.
+      # Make an HTTP(S) request to a geocoding API and
+      # return the response object.
       #
-      def cache
-        Geocoder.cache
+      def make_api_request(query)
+        timeout(configuration.timeout) do
+          uri = URI.parse(query_url(query))
+          client = http_client.new(uri.host, uri.port)
+          client.use_ssl = true if configuration.use_https
+          client.get(uri.request_uri, configuration.http_headers)
+        end
+      end
+
+      def check_api_key_configuration!(query)
+        key_parts = query.lookup.required_api_key_parts
+        if key_parts.size > Array(configuration.api_key).size
+          parts_string = key_parts.size == 1 ? key_parts.first : key_parts
+          raise Geocoder::ConfigurationError,
+            "The #{query.lookup.name} API requires a key to be configured: " +
+            parts_string.inspect
+        end
       end
 
       ##

data/lib/geocoder/lookups/bing.rb

@@ -4,34 +4,44 @@ require "geocoder/results/bing"
 module Geocoder::Lookup
   class Bing < Base
 
+    def name
+      "Bing"
+    end
+
     def map_link_url(coordinates)
       "http://www.bing.com/maps/default.aspx?cp=#{coordinates.join('~')}"
     end
 
+    def required_api_key_parts
+      ["key"]
+    end
+
+    def query_url(query)
+      "#{protocol}://dev.virtualearth.net/REST/v1/Locations" +
+        (query.reverse_geocode? ? "/#{query.sanitized_text}?" : "?") +
+        url_query_string(query)
+    end
+
     private # ---------------------------------------------------------------
 
     def results(query)
       return [] unless doc = fetch_data(query)
 
-      if doc['statusDescription'] == "OK"
+      if doc['statusCode'] == 200
         return doc['resourceSets'].first['estimatedTotal'] > 0 ? doc['resourceSets'].first['resources'] : []
+      elsif doc['statusCode'] == 401 and doc["authenticationResultCode"] == "InvalidCredentials"
+        raise_error(Geocoder::InvalidApiKey) || warn("Invalid Bing API key.")
       else
         warn "Bing Geocoding API error: #{doc['statusCode']} (#{doc['statusDescription']})."
-        return []
       end
+      return []
     end
 
     def query_url_params(query)
-      super.merge(
-        :key => Geocoder::Configuration.api_key,
+      {
+        :key => configuration.api_key,
         :query => query.reverse_geocode? ? nil : query.sanitized_text
-      )
-    end
-
-    def query_url(query)
-      "http://dev.virtualearth.net/REST/v1/Locations" +
-        (query.reverse_geocode? ? "/#{query.sanitized_text}?" : "?") +
-        url_query_string(query)
+      }.merge(super)
     end
   end
 end