geocoder 1.1.3 → 1.1.6

data/lib/geocoder/lookups/base.rb

@@ -13,8 +13,24 @@ 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.
@@ -23,18 +39,9 @@ module Geocoder
       # "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)
-
-        # if coordinates given as string, turn into array
-        query = query.split(/\s*,\s*/) if coordinates?(query)
-
-        if query.is_a?(Array)
-          reverse = true
-          query = query.join(',')
-        else
-          reverse = false
-        end
-        results(query, reverse).map{ |r| 
+      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
@@ -51,16 +58,37 @@ 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
 
       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)
@@ -77,15 +105,28 @@ module Geocoder
       ##
       # Geocoder::Result object or nil on timeout or other error.
       #
-      def results(query, reverse = false)
+      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
+
       ##
-      # 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, reverse = false)
-        fail
+      def cache_key(query)
+        query_url(query)
       end
 
       ##
@@ -100,7 +141,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
@@ -111,13 +152,13 @@ module Geocoder
       ##
       # Returns a parsed search result (Ruby hash).
       #
-      def fetch_data(query, reverse = false)
-        parse_raw_data fetch_raw_data(query, reverse)
+      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 " +
-          "(see Geocoder::Configuration.timeout to set limit)."
+          "(use Geocoder.configure(:timeout => ...) to set limit)."
       end
 
       ##
@@ -138,51 +179,60 @@ module Geocoder
       # Set in configuration but not available for every service.
       #
       def protocol
-        "http" + (Geocoder::Configuration.use_https ? "s" : "")
-      end
-
-      ##
-      # Fetches a raw search result (JSON string).
-      #
-      def fetch_raw_data(query, reverse = false)
-        timeout(Geocoder::Configuration.timeout) do
-          url = query_url(query, reverse)
-          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
-          end
-          body
-        end
+        "http" + (configuration.use_https ? "s" : "")
       end
 
       ##
-      # The working Cache object.
+      # Fetch a raw geocoding result (JSON string).
+      # The result might or might not be cached.
       #
-      def cache
-        Geocoder.cache
+      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
 
       ##
-      # Is the given string a loopback IP address?
-      #
-      def loopback_address?(ip)
-        !!(ip == "0.0.0.0" or ip.to_s.match(/^127/))
+      # 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
 
       ##
-      # Does the given string look like latitude/longitude coordinates?
+      # The working Cache object.
       #
-      def coordinates?(value)
-        value.is_a?(String) and !!value.to_s.match(/^-?[0-9\.]+, *-?[0-9\.]+$/)
+      def cache
+        if @cache.nil? and store = configuration.cache
+          @cache = Cache.new(store, configuration.cache_prefix)
+        end
+        @cache
       end
 
       ##

data/lib/geocoder/lookups/bing.rb

@@ -4,30 +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, reverse = false)
-      return [] unless doc = fetch_data(query, reverse)
+    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(query, reverse = false)
-      params = {:key => Geocoder::Configuration.api_key}
-      params[:query] = query unless reverse
-
-      base_url = "http://dev.virtualearth.net/REST/v1/Locations"
-      url_tail = reverse ? "/#{query}?" : "?"
-      base_url + url_tail + hash_to_query(params)
+    def query_url_params(query)
+      {
+        :key => configuration.api_key,
+        :query => query.reverse_geocode? ? nil : query.sanitized_text
+      }.merge(super)
     end
   end
 end

data/lib/geocoder/lookups/freegeoip.rb

@@ -4,17 +4,25 @@ require 'geocoder/results/freegeoip'
 module Geocoder::Lookup
   class Freegeoip < Base
 
+    def name
+      "FreeGeoIP"
+    end
+
+    def query_url(query)
+      "#{protocol}://freegeoip.net/json/#{query.sanitized_text}"
+    end
+
     private # ---------------------------------------------------------------
 
     def parse_raw_data(raw_data)
       raw_data.match(/^<html><title>404/) ? nil : super(raw_data)
     end
 
-    def results(query, reverse = false)
+    def results(query)
       # don't look up a loopback address, just return the stored result
-      return [reserved_result(query)] if loopback_address?(query)
+      return [reserved_result(query.text)] if query.loopback_ip_address?
       begin
-        return (doc = fetch_data(query, reverse)) ? [doc] : []
+        return (doc = fetch_data(query)) ? [doc] : []
       rescue StandardError => err # Freegeoip.net returns HTML on bad request
         raise_error(err)
         return []
@@ -35,9 +43,5 @@ module Geocoder::Lookup
         "country_code" => "RD"
       }
     end
-
-    def query_url(query, reverse = false)
-      "http://freegeoip.net/json/#{query}"
-    end
   end
 end

data/lib/geocoder/lookups/geocoder_ca.rb

@@ -4,10 +4,18 @@ require "geocoder/results/geocoder_ca"
 module Geocoder::Lookup
   class GeocoderCa < Base
 
+    def name
+      "Geocoder.ca"
+    end
+
+    def query_url(query)
+      "#{protocol}://geocoder.ca/?" + url_query_string(query)
+    end
+
     private # ---------------------------------------------------------------
 
-    def results(query, reverse = false)
-      return [] unless doc = fetch_data(query, reverse)
+    def results(query)
+      return [] unless doc = fetch_data(query)
       if doc['error'].nil?
         return [doc]
       elsif doc['error']['code'] == "005"
@@ -18,24 +26,24 @@ module Geocoder::Lookup
       return []
     end
 
-    def query_url(query, reverse = false)
+    def query_url_params(query)
       params = {
         :geoit    => "xml",
         :jsonp    => 1,
         :callback => "test",
-        :auth     => Geocoder::Configuration.api_key
-      }
-      if reverse
-        lat,lon = query.split(',')
+        :auth     => configuration.api_key
+      }.merge(super)
+      if query.reverse_geocode?
+        lat,lon = query.coordinates
         params[:latt] = lat
         params[:longt] = lon
         params[:corner] = 1
         params[:reverse] = 1
       else
-        params[:locate] = query
+        params[:locate] = query.sanitized_text
         params[:showpostal] = 1
       end
-      "http://geocoder.ca/?" + hash_to_query(params)
+      params
     end
 
     def parse_raw_data(raw_data)

data/lib/geocoder/lookups/google.rb

@@ -4,14 +4,22 @@ require "geocoder/results/google"
 module Geocoder::Lookup
   class Google < Base
 
+    def name
+      "Google"
+    end
+
     def map_link_url(coordinates)
       "http://maps.google.com/maps?q=#{coordinates.join(',')}"
     end
 
+    def query_url(query)
+      "#{protocol}://maps.googleapis.com/maps/api/geocode/json?" + url_query_string(query)
+    end
+
     private # ---------------------------------------------------------------
 
-    def results(query, reverse = false)
-      return [] unless doc = fetch_data(query, reverse)
+    def results(query)
+      return [] unless doc = fetch_data(query)
       case doc['status']; when "OK" # OK status implies >0 results
         return doc['results']
       when "OVER_QUERY_LIMIT"
@@ -27,15 +35,28 @@ module Geocoder::Lookup
       return []
     end
 
-    def query_url(query, reverse = false)
+    def query_url_google_params(query)
       params = {
-        (reverse ? :latlng : :address) => query,
+        (query.reverse_geocode? ? :latlng : :address) => query.sanitized_text,
         :sensor => "false",
-        :language => Geocoder::Configuration.language,
-        :key => Geocoder::Configuration.api_key
+        :language => configuration.language
       }
-      "#{protocol}://maps.googleapis.com/maps/api/geocode/json?" + hash_to_query(params)
+      unless (bounds = query.options[:bounds]).nil?
+        params[:bounds] = bounds.map{ |point| "%f,%f" % point }.join('|')
+      end
+      unless (region = query.options[:region]).nil?
+        params[:region] = region
+      end
+      unless (components = query.options[:components]).nil?
+        params[:components] = components.is_a?(Array) ? components.join("|") : components
+      end
+      params
+    end
+
+    def query_url_params(query)
+      query_url_google_params(query).merge(
+        :key => configuration.api_key
+      ).merge(super)
     end
   end
 end
-

data/lib/geocoder/lookups/google_premier.rb

@@ -6,22 +6,31 @@ require 'geocoder/results/google_premier'
 module Geocoder::Lookup
   class GooglePremier < Google
 
-    private # ---------------------------------------------------------------
+    def name
+      "Google Premier"
+    end
+
+    def required_api_key_parts
+      ["private key", "client", "channel"]
+    end
 
-    def query_url(query, reverse = false)
-      params = {
-        (reverse ? :latlng : :address) => query,
-        :sensor => 'false',
-        :language => Geocoder::Configuration.language,
-        :client => Geocoder::Configuration.api_key[1],
-        :channel => Geocoder::Configuration.api_key[2]
-      }.reject{ |key, value| value.nil? }
-      path = "/maps/api/geocode/json?#{hash_to_query(params)}"
+    def query_url(query)
+      path = "/maps/api/geocode/json?" + url_query_string(query)
       "#{protocol}://maps.googleapis.com#{path}&signature=#{sign(path)}"
     end
 
+    private # ---------------------------------------------------------------
+
+    def query_url_params(query)
+      query_url_google_params(query).merge(super).merge(
+        :key => nil, # don't use param inherited from Google lookup
+        :client => configuration.api_key[1],
+        :channel => configuration.api_key[2]
+      )
+    end
+
     def sign(string)
-      raw_private_key = url_safe_base64_decode(Geocoder::Configuration.api_key[0])
+      raw_private_key = url_safe_base64_decode(configuration.api_key[0])
       digest = OpenSSL::Digest::Digest.new('sha1')
       raw_signature = OpenSSL::HMAC.digest(digest, raw_private_key, string)
       url_safe_base64_encode(raw_signature)

data/lib/geocoder/lookups/mapquest.rb

@@ -1,33 +1,43 @@
+require 'cgi'
 require 'geocoder/lookups/base'
 require "geocoder/results/mapquest"
 
 module Geocoder::Lookup
   class Mapquest < Base
 
+    def name
+      "Mapquest"
+    end
+
+    def required_api_key_parts
+      ["key"]
+    end
+
+    def query_url(query)
+      key = configuration.api_key
+      domain = key ? "www" : "open"
+      url = "#{protocol}://#{domain}.mapquestapi.com/geocoding/v1/#{search_type(query)}?"
+      url + url_query_string(query)
+    end
+
     private # ---------------------------------------------------------------
 
-    def results(query, reverse = false)
-      return [] unless doc = fetch_data(query, reverse)
-      doc.is_a?(Array) ? doc : [doc]
+    def search_type(query)
+      query.reverse_geocode? ? "reverse" : "address"
     end
 
-    def query_url(query, reverse = false)
-      params = {
-        :format => "json",
-        :polygon => "1",
-        :addressdetails => "1",
-        :"accept-language" => Geocoder::Configuration.language
-      }
-      if (reverse)
-        method = 'reverse'
-        parts = query.split(/\s*,\s*/);
-        params[:lat] = parts[0]
-        params[:lon] = parts[1]
-      else
-        method = 'search'
-        params[:q] = query
+    def query_url_params(query)
+      params = { :location => query.sanitized_text }
+      if key = configuration.api_key
+        params[:key] = CGI.unescape(key)
       end
-      "http://open.mapquestapi.com/#{method}?" + hash_to_query(params)
+      params.merge(super)
+    end
+
+    def results(query)
+      return [] unless doc = fetch_data(query)
+      doc["results"][0]['locations']
     end
+
   end
 end

data/lib/geocoder/lookups/maxmind.rb

@@ -0,0 +1,72 @@
+require 'geocoder/lookups/base'
+require 'geocoder/results/maxmind'
+require 'csv'
+
+module Geocoder::Lookup
+  class Maxmind < Base
+
+    def name
+      "MaxMind"
+    end
+
+    def query_url(query)
+      "#{protocol}://geoip.maxmind.com/#{service_code}?" + url_query_string(query)
+    end
+
+    private # ---------------------------------------------------------------
+
+    def service_code
+      if s = configuration[:service] and services.keys.include?(s)
+        services[s]
+      else
+        raise(
+          Geocoder::ConfigurationError,
+          "When using MaxMind you MUST specify a service name: " +
+          "Geocoder.configure(:maxmind => {:service => ...}), " +
+          "where '...' is one of: #{services.keys.inspect}"
+        )
+      end
+    end
+
+    ##
+    # Service names mapped to code used in URL.
+    #
+    def services
+      {
+        :country => "a",
+        :city => "b",
+        :city_isp_org => "f",
+        :omni => "e"
+      }
+    end
+
+    def results(query)
+      # don't look up a loopback address, just return the stored result
+      return [reserved_result] if query.loopback_ip_address?
+      doc = fetch_data(query)
+      if doc and doc.is_a?(Array)
+        if doc.last.nil?
+          return [doc]
+        elsif doc.last == "INVALID_LICENSE_KEY"
+          raise_error(Geocoder::InvalidApiKey) || warn("Invalid MaxMind API key.")
+        end
+      end
+      return []
+    end
+
+    def parse_raw_data(raw_data)
+      CSV.parse_line raw_data
+    end
+
+    def reserved_result
+      ",,,,0,0,0,0,,,"
+    end
+
+    def query_url_params(query)
+      {
+        :l => configuration.api_key,
+        :i => query.sanitized_text
+      }.merge(super)
+    end
+  end
+end

data/lib/geocoder/lookups/nominatim.rb

@@ -4,34 +4,42 @@ require "geocoder/results/nominatim"
 module Geocoder::Lookup
   class Nominatim < Base
 
+    def name
+      "Nominatim"
+    end
+
     def map_link_url(coordinates)
       "http://www.openstreetmap.org/?lat=#{coordinates[0]}&lon=#{coordinates[1]}&zoom=15&layers=M"
     end
 
+    def query_url(query)
+      method = query.reverse_geocode? ? "reverse" : "search"
+      host = configuration[:host] || "nominatim.openstreetmap.org"
+      "#{protocol}://#{host}/#{method}?" + url_query_string(query)
+    end
+
     private # ---------------------------------------------------------------
 
-    def results(query, reverse = false)
-      return [] unless doc = fetch_data(query, reverse)
+    def results(query)
+      return [] unless doc = fetch_data(query)
       doc.is_a?(Array) ? doc : [doc]
     end
 
-    def query_url(query, reverse = false)
+    def query_url_params(query)
       params = {
         :format => "json",
         :polygon => "1",
         :addressdetails => "1",
-        :"accept-language" => Geocoder::Configuration.language
-      }
-      if (reverse)
-        method = 'reverse'
-        parts = query.split(/\s*,\s*/);
-        params[:lat] = parts[0]
-        params[:lon] = parts[1]
+        :"accept-language" => configuration.language
+      }.merge(super)
+      if query.reverse_geocode?
+        lat,lon = query.coordinates
+        params[:lat] = lat
+        params[:lon] = lon
       else
-        method = 'search'
-        params[:q] = query
+        params[:q] = query.sanitized_text
       end
-      "http://nominatim.openstreetmap.org/#{method}?" + hash_to_query(params)
+      params
     end
   end
 end