geocoder2 0.1.0

data/lib/geocoder2/lookup.rb

@@ -0,0 +1,86 @@
+module Geocoder2
+  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
+      [
+        :dstk,
+        :esri,
+        :google,
+        :google_premier,
+        :yahoo,
+        :bing,
+        :geocoder_ca,
+        :geocoder_us,
+        :yandex,
+        :nominatim,
+        :mapquest,
+        :ovi,
+        :baidu,
+        :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 Geocoder2::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)
+        Geocoder2::Lookup.const_get(classify_name(name)).new
+      else
+        valids = all_services.map(&:inspect).join(", ")
+        raise ConfigurationError, "Please specify a valid lookup for Geocoder2 " +
+          "(#{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
+
+Geocoder2::Lookup.all_services.each do |name|
+  require "geocoder2/lookups/#{name}"
+end

data/lib/geocoder2/lookups/baidu.rb

@@ -0,0 +1,54 @@
+require 'geocoder2/lookups/base'
+require "geocoder2/results/baidu"
+
+module Geocoder2::Lookup
+  class Baidu < Base
+
+    def name
+      "Baidu"
+    end
+
+    def required_api_key_parts
+      ["key"]
+    end
+
+    def query_url(query)
+      "http://api.map.baidu.com/geocoder2/v2/?" + url_query_string(query)
+    end
+
+    private # ---------------------------------------------------------------
+
+    def results(query, reverse = false)
+      return [] unless doc = fetch_data(query)
+      case doc['status']; when 0
+        return [doc['result']] unless doc['result'].blank?
+      when 1, 3, 4
+        raise_error(Geocoder2::Error, messages) ||
+          warn("Baidu Geocoding API error: server error.")
+      when 2
+        raise_error(Geocoder2::InvalidRequest, messages) ||
+          warn("Baidu Geocoding API error: invalid request.")
+      when 5
+        raise_error(Geocoder2::InvalidApiKey, messages) ||
+          warn("Baidu Geocoding API error: invalid api key.")
+      when 101, 102, 200..299
+        raise_error(Geocoder2::RequestDenied) ||
+          warn("Baidu Geocoding API error: request denied.")
+      when 300..399
+        raise_error(Geocoder2::OverQueryLimitError) ||
+          warn("Baidu Geocoding API error: over query limit.")
+      end
+      return []
+    end
+
+    def query_url_params(query)
+      {
+        (query.reverse_geocode? ? :location : :address) => query.sanitized_text,
+        :ak => configuration.api_key,
+        :output => "json"
+      }.merge(super)
+    end
+
+  end
+end
+

data/lib/geocoder2/lookups/base.rb

@@ -0,0 +1,266 @@
+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 geocoder2 results."
+  end
+end
+
+module Geocoder2
+  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 Geocoder2::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>Geocoder2::Result</tt>s.
+      #
+      def search(query, options = {})
+        query = Geocoder2::Query.new(query, options) unless query.is_a?(Geocoder2::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
+
+      ##
+      # 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
+        Geocoder2.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 = !!(proxy =~ /^#{protocol}/) ? proxy : 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
+
+      ##
+      # Geocoder2::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
+        Geocoder2::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 Geocoder2.configure(:timeout => ...) to set limit)."
+      end
+
+      def parse_json(data)
+        if defined?(ActiveSupport::JSON)
+          ActiveSupport::JSON.decode(data)
+        else
+          JSON.parse(data)
+        end
+      end
+
+      ##
+      # Parses a raw search result (returns hash or array).
+      #
+      def parse_raw_data(raw_data)
+        parse_json(raw_data)
+      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
+
+      def valid_response?(response)
+        (200..399).include?(response.code.to_i)
+      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 valid_response?(response)
+            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))
+          puts "DEBUG: #{uri.inspect}"
+          client = http_client.new(uri.host, uri.port)
+          client.use_ssl = true if configuration.use_https
+          client.get(uri.request_uri, configuration.http_headers)
+
+          #http_client.start(uri.host, uri.port) do |client|
+          #  client.use_ssl = true if configuration.use_https
+          #  req = Net::HTTP::Get.new(uri.request_uri, configuration.http_headers)
+          #  req.basic_auth(uri.user, uri.password) if uri.user and uri.password
+          #  client.request(req)
+          #end
+        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 Geocoder2::ConfigurationError,
+            "The #{query.lookup.name} API requires a key to be configured: " +
+            parts_string.inspect
+        end
+      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

data/lib/geocoder2/lookups/bing.rb

@@ -0,0 +1,47 @@
+require 'geocoder2/lookups/base'
+require "geocoder2/results/bing"
+
+module Geocoder2::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['statusCode'] == 200
+        return doc['resourceSets'].first['estimatedTotal'] > 0 ? doc['resourceSets'].first['resources'] : []
+      elsif doc['statusCode'] == 401 and doc["authenticationResultCode"] == "InvalidCredentials"
+        raise_error(Geocoder2::InvalidApiKey) || warn("Invalid Bing API key.")
+      else
+        warn "Bing Geocoding API error: #{doc['statusCode']} (#{doc['statusDescription']})."
+      end
+      return []
+    end
+
+    def query_url_params(query)
+      {
+        :key => configuration.api_key,
+        :query => query.reverse_geocode? ? nil : query.sanitized_text
+      }.merge(super)
+    end
+  end
+end

data/lib/geocoder2/lookups/dstk.rb

@@ -0,0 +1,20 @@
+# More information about the Data Science Toolkit can be found at:
+# http://www.datasciencetoolkit.org/. The provided APIs mimic the
+# Google geocoding api.
+
+require 'geocoder2/lookups/google'
+require 'geocoder2/results/dstk'
+
+module Geocoder2::Lookup
+  class Dstk < Google
+
+    def name
+      "Data Science Toolkit"
+    end
+
+    def query_url(query)
+      host = configuration[:host] || "www.datasciencetoolkit.org"
+      "#{protocol}://#{host}/maps/api/geocode/json?" + url_query_string(query)
+    end
+  end
+end

data/lib/geocoder2/lookups/esri.rb

@@ -0,0 +1,48 @@
+require 'geocoder2/lookups/base'
+require "geocoder2/results/esri"
+
+module Geocoder2::Lookup
+  class Esri < Base
+    
+    def name
+      "Esri"
+    end
+
+    def query_url(query)
+      search_keyword = query.reverse_geocode? ? "reverseGeocode" : "find"
+
+      "#{protocol}://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/#{search_keyword}?" +
+        url_query_string(query)
+    end
+
+    private # ---------------------------------------------------------------
+
+    def results(query)
+      return [] unless doc = fetch_data(query)
+
+      if (!query.reverse_geocode?)
+        return [] if doc['locations'].empty?
+      end
+
+      if (doc['error'].nil?)
+        return [ doc ]
+      else
+        return []
+      end
+    end
+
+    def query_url_params(query)
+      params = {
+        :f => "pjson",
+        :outFields => "*"
+      }
+      if query.reverse_geocode?
+        params[:location] = query.coordinates.reverse.join(',')
+      else
+        params[:text] = query.sanitized_text
+      end
+      params.merge(super)
+    end
+
+  end
+end

data/lib/geocoder2/lookups/freegeoip.rb

@@ -0,0 +1,43 @@
+require 'geocoder2/lookups/base'
+require 'geocoder2/results/freegeoip'
+
+module Geocoder2::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)
+      # don't look up a loopback address, just return the stored result
+      return [reserved_result(query.text)] if query.loopback_ip_address?
+      # note: Freegeoip.net returns plain text "Not Found" on bad request
+      (doc = fetch_data(query)) ? [doc] : []
+    end
+
+    def reserved_result(ip)
+      {
+        "ip"           => ip,
+        "city"         => "",
+        "region_code"  => "",
+        "region_name"  => "",
+        "metrocode"    => "",
+        "zipcode"      => "",
+        "latitude"     => "0",
+        "longitude"    => "0",
+        "country_name" => "Reserved",
+        "country_code" => "RD"
+      }
+    end
+  end
+end

data/lib/geocoder2/lookups/geocoder_ca.rb

@@ -0,0 +1,54 @@
+require 'geocoder2/lookups/base'
+require "geocoder2/results/geocoder_ca"
+
+module Geocoder2::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)
+      return [] unless doc = fetch_data(query)
+      if doc['error'].nil?
+        return [doc]
+      elsif doc['error']['code'] == "005"
+        # "Postal Code is not in the proper Format" => no results, just shut up
+      else
+        warn "Geocoder2.ca service error: #{doc['error']['code']} (#{doc['error']['description']})."
+      end
+      return []
+    end
+
+    def query_url_params(query)
+      params = {
+        :geoit    => "xml",
+        :jsonp    => 1,
+        :callback => "test",
+        :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.sanitized_text
+        params[:showpostal] = 1
+      end
+      params
+    end
+
+    def parse_raw_data(raw_data)
+      super raw_data[/^test\((.*)\)\;\s*$/, 1]
+    end
+  end
+end
+

data/lib/geocoder2/lookups/geocoder_us.rb

@@ -0,0 +1,39 @@
+require 'geocoder2/lookups/base'
+require "geocoder2/results/geocoder_us"
+
+module Geocoder2::Lookup
+  class GeocoderUs < Base
+
+    def name
+      "Geocoder2.us"
+    end
+
+    def query_url(query)
+      if configuration.api_key
+        "http://#{configuration.api_key}@geocoder2.us/member/service/csv/geocode?" + url_query_string(query)
+      else
+        "http://geocoder2.us/service/csv/geocode?" + url_query_string(query)
+      end
+    end
+
+    private
+
+    def results(query)
+      return [] unless doc = fetch_data(query)
+      if doc[0].to_s =~ /^(\d+)\:/
+        return []
+      else
+        return [doc.size == 5 ? ((doc[0..1] << nil) + doc[2..4]) : doc]
+      end
+    end
+
+    def query_url_params(query)
+      (query.text =~ /^\d{5}(?:-\d{4})?$/ ? {:zip => query} : {:address => query.sanitized_text}).merge(super)
+    end
+
+    def parse_raw_data(raw_data)
+      raw_data.chomp.split(',')
+    end
+  end
+end
+