geocoder-sgonyea 1.1.6.1

data/lib/geocoder/cli.rb

@@ -0,0 +1,114 @@
+require 'geocoder'
+require 'optparse'
+
+module Geocoder
+  class Cli
+
+    def self.run(args, out = STDOUT)
+      show_url  = false
+      show_json = false
+
+      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
+            Geocoder.configure(:api_key => key_parts)
+          else
+            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.configure(:language => language)
+        end
+
+        opts.on("-p <proxy>", "--proxy <proxy>",
+          "HTTP proxy server to use (user:pass@host:port)") do |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.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.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 "geocoder/version"
+          out << "Geocoder #{Geocoder::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/geocoder\n"
+          exit
+        end
+      }.parse!(args)
+
+      query = args.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 = Geocoder::Query.new(query)
+        out << q.url + "\n"
+        exit 0
+      end
+
+      if show_json
+        q = Geocoder::Query.new(query)
+        out << q.lookup.send(:fetch_raw_data, q) + "\n"
+        exit 0
+      end
+
+      if (result = Geocoder.search(query).first)
+        google = Geocoder::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/geocoder/configuration.rb

@@ -0,0 +1,130 @@
+require 'singleton'
+require 'geocoder/configuration_hash'
+
+module Geocoder
+
+  ##
+  # Configuration options should be set by passing a hash:
+  #
+  #   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
+
+  ##
+  # 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 = Geocoder::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] = "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
+      @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/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

@@ -0,0 +1,21 @@
+module Geocoder
+
+  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

data/lib/geocoder/lookup.rb

@@ -0,0 +1,82 @@
+module Geocoder
+  module Lookup
+    extend self
+
+    ##
+    # Array of valid Lookup service names.
+    #
+    def all_services
+      street_services + ip_services
+    end
+
+    ##
+    # Array of valid Lookup service names, excluding :test.
+    #
+    def all_services_except_test
+      all_services - [:test]
+    end
+
+    ##
+    # All street address lookup services, default first.
+    #
+    def street_services
+      [
+        :google,
+        :google_premier,
+        :yahoo,
+        :bing,
+        :geocoder_ca,
+        :yandex,
+        :nominatim,
+        :mapquest,
+        :ovi,
+        :test
+      ]
+    end
+
+    ##
+    # All IP address lookup services, default first.
+    #
+    def ip_services
+      [:freegeoip, :maxmind]
+    end
+
+    ##
+    # Retrieve a Lookup object from the store.
+    # Use this instead of Geocoder::Lookup::X.new to get an
+    # already-configured Lookup object.
+    #
+    def get(name)
+      @services = {} unless defined?(@services)
+      @services[name] = spawn(name) unless @services.include?(name)
+      @services[name]
+    end
+
+
+    private # -----------------------------------------------------------------
+
+    ##
+    # Spawn a Lookup of the given name.
+    #
+    def spawn(name)
+      if all_services.include?(name)
+        Geocoder::Lookup.const_get(classify_name(name)).new
+      else
+        valids = all_services.map(&:inspect).join(", ")
+        raise ConfigurationError, "Please specify a valid lookup for Geocoder " +
+          "(#{name.inspect} is not one of: #{valids})."
+      end
+    end
+
+    ##
+    # Convert an "underscore" version of a name into a "class" version.
+    #
+    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}"
+end

data/lib/geocoder/lookups/base.rb

@@ -0,0 +1,250 @@
+require 'net/http'
+require 'net/https'
+require 'uri'
+
+unless defined?(ActiveSupport::JSON)
+  begin
+    require 'rubygems' # for Ruby 1.8
+    require 'json'
+  rescue LoadError
+    raise LoadError, "Please install the 'json' or 'json_pure' gem to parse geocoder results."
+  end
+end
+
+module Geocoder
+  module Lookup
+
+    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.
+      #
+      # Takes a search string (eg: "Mississippi Coast Coliseumf, Biloxi, MS",
+      # "205.128.54.202") for geocoding, or coordinates (latitude, longitude)
+      # for reverse geocoding. Returns an array of <tt>Geocoder::Result</tt>s.
+      #
+      def search(query, options = {})
+        query = Geocoder::Query.new(query, options) unless query.is_a?(Geocoder::Query)
+        results(query).map{ |r|
+          result = result_class.new(r)
+          result.cache_hit = @cache_hit if cache
+          result
+        }
+      end
+
+      ##
+      # Return the URL for a map of the given coordinates.
+      #
+      # Not necessarily implemented by all subclasses as only some lookups
+      # also provide maps.
+      #
+      def map_link_url(coordinates)
+        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
+
+      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 configuration.use_https}"
+        proxy_name = "#{protocol}_proxy"
+        if proxy = configuration.send(proxy_name)
+          proxy_url = protocol + '://' + proxy
+          begin
+            uri = URI.parse(proxy_url)
+          rescue URI::InvalidURIError
+            raise ConfigurationError,
+              "Error parsing #{protocol.upcase} proxy URL: '#{proxy_url}'"
+          end
+          Net::HTTP::Proxy(uri.host, uri.port, uri.user, uri.password)
+        else
+          Net::HTTP
+        end
+      end
+
+      ##
+      # Geocoder::Result object or nil on timeout or other error.
+      #
+      def results(query)
+        fail
+      end
+
+      def query_url_params(query)
+        query.options[:params] || {}
+      end
+
+      def url_query_string(query)
+        hash_to_query(
+          query_url_params(query).reject{ |key,value| value.nil? }
+        )
+      end
+
+      ##
+      # 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 cache_key(query)
+        query_url(query)
+      end
+
+      ##
+      # Class of the result objects
+      #
+      def result_class
+        Geocoder::Result.const_get(self.class.to_s.split(":").last)
+      end
+
+      ##
+      # Raise exception if configuration specifies it should be raised.
+      # Return false if exception not raised.
+      #
+      def raise_error(error, message = nil)
+        exceptions = configuration.always_raise
+        if exceptions == :all or exceptions.include?( error.is_a?(Class) ? error : error.class )
+          raise error, message
+        else
+          false
+        end
+      end
+
+      ##
+      # Returns a parsed search result (Ruby hash).
+      #
+      def fetch_data(query)
+        parse_raw_data fetch_raw_data(query)
+      rescue SocketError => err
+        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 " +
+          "(use Geocoder.configure(:timeout => ...) to set limit)."
+      end
+
+      ##
+      # Parses a raw search result (returns hash or array).
+      #
+      def parse_raw_data(raw_data)
+        if defined?(ActiveSupport::JSON)
+          ActiveSupport::JSON.decode(raw_data)
+        else
+          JSON.parse(raw_data)
+        end
+      rescue
+        warn "Geocoding API's response was not valid JSON."
+      end
+
+      ##
+      # Protocol to use for communication with geocoding services.
+      # Set in configuration but not available for every service.
+      #
+      def protocol
+        "http" + (configuration.use_https ? "s" : "")
+      end
+
+      ##
+      # Fetch a raw geocoding result (JSON string).
+      # The result might or might not be cached.
+      #
+      def fetch_raw_data(query)
+        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
+          @cache_hit = false
+        end
+        body
+      end
+
+      ##
+      # Make an HTTP(S) request to a geocoding API and
+      # return the response object.
+      #
+      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
+
+      ##
+      # The working Cache object.
+      #
+      def cache
+        if @cache.nil? and store = configuration.cache
+          @cache = Cache.new(store, configuration.cache_prefix)
+        end
+        @cache
+      end
+
+      ##
+      # Simulate ActiveSupport's Object#to_query.
+      # Removes any keys with nil value.
+      #
+      def hash_to_query(hash)
+        require 'cgi' unless defined?(CGI) && defined?(CGI.escape)
+        hash.collect{ |p|
+          p[1].nil? ? nil : p.map{ |i| CGI.escape i.to_s } * '='
+        }.compact.sort * '&'
+      end
+    end
+  end
+end