drifter 0.1.0

data/lib/drifter/geocoders/google.rb

@@ -0,0 +1,91 @@
+require 'drifter/geocoders/base'
+
+module Drifter
+  module Geocoders
+    
+    # This class adds support for Google's geocoding API:
+    # http://code.google.com/apis/maps/documentation/geocoding/
+    class Google < Drifter::Geocoders::Base
+
+      GOOGLE_BASE_URI = 'http://maps.googleapis.com/maps/api/geocode/json'
+
+
+      # nodoc
+      def self.base_uri
+        GOOGLE_BASE_URI
+      end
+
+
+      # This method works exactly like Drifter::Geocoders::Yahoo.geocode()
+      # See that method for more info.  The returned Drifter::Location objects
+      # have the following attributes:
+      #
+      #   :address, :city, :state, :state_code, :country, :country_code,
+      #   :post_code, :lat, :lng
+      #
+      # Additional google specific attributes can be accessed using the Location
+      # object's data() method
+      def self.geocode(location, params={})
+
+        params[:address] = location
+
+        # check for reverse gecoding
+        lat, lng = Drifter.extract_latlng(location)
+        if lat && lng
+          params.delete(:address)
+          params[:latlng] = [lat, lng].join(',')
+        end
+
+        uri = query_uri(params)
+        response = fetch(uri)
+
+        # check for errors and return if necassary
+        doc = JSON.parse(response)
+        unless ["OK", "ZERO_RESULTS"].include?(doc["status"])
+          @@last_error = { :code => doc["status"], :message => doc["status"] }
+          return nil
+        end
+
+        # still here so safe to clear errors
+        @@last_error = nil
+
+        # is there anything to parse?
+        return [] if doc["status"] == "ZERO_RESULTS"
+
+        doc["results"].collect do |result|
+          loc = Drifter::Location.new
+          loc.raw_data_format = :hash
+          loc.raw_data = result
+          loc.geocoder = :google
+
+          loc.address = result["formatted_address"]
+          loc.lat = result["geometry"]["location"]["lat"]
+          loc.lng = result["geometry"]["location"]["lng"]
+
+          result["address_components"].each do |comp|
+            loc.country_code = comp["short_name"] if comp["types"].include?("country")
+            loc.country = comp["long_name"] if comp["types"].include?("country")
+            loc.city = comp["long_name"] if comp["types"].include?("locality")
+            loc.post_code = comp["long_name"] if comp["types"].include?("postal_code")
+            loc.state = comp["long_name"] if comp["types"].include?("administrative_area_level_1")
+            loc.state_code = comp["short_name"] if comp["types"].include?("administrative_area_level_1")
+          end
+          loc
+        end
+
+      end
+
+
+      # Google requires a 'sensor' parameter. If none is set, it defaults to false
+      # See their docs for more info
+      def self.query_uri(params={})
+        params[:sensor] ||= 'false'
+        uri = URI.parse(base_uri)
+        uri.query = hash_to_query_string(params)
+        return uri
+      end
+
+
+    end
+  end
+end

data/lib/drifter/geocoders/hostip.rb

@@ -0,0 +1,92 @@
+require 'drifter/geocoders/base'
+module Drifter
+  module Geocoders
+
+    # This class adds support for basic ip address geocoding using the
+    # free API from hostip.info
+    class HostIP < Drifter::Geocoders::Base
+
+      @@lat_error = nil
+      BASE_URI = 'http://api.hostip.info/get_html.php'
+      IP_PATTERN = /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/
+
+
+      # nodoc
+      def self.base_uri
+        BASE_URI
+      end
+
+
+      # geocodes the given IP address.
+      #
+      # On Success: returns an array with one Drifter::Location object
+      # On Failure: returns an empty array
+      # On Error:   returns nil. last_error() holds error information
+      def self.geocode(ip, options={})
+
+        # TODO: tests!
+        
+        # make sure it's an IP address
+        unless ip.to_s =~ IP_PATTERN
+          @@last_error = { :message => ip.to_s + " is not a valid IP address" }
+          return nil
+        end
+
+        # the position param is needed for lat/lng
+        options[:ip] = ip.to_s
+        options[:position] = true
+        uri = query_uri(options)
+
+        # get the response, should be 5 lines (6 but one is blank)
+        response = fetch(uri)
+        response = response.to_s.split("\n").collect { |line| line.empty?? nil : line }
+        response.compact!
+        unless response.size == 5
+          @@last_error = { :message => "HostIP returned a response that #{name} doesn't understand" }
+          return nil
+        end
+
+        # still here so the errors can be cleared
+        @@last_error = nil
+
+        # however, hostip wont return an error response for bad queries.
+        # It just returns blank values and XX as the country code.  Treat that a
+        # a successful request with no results:
+        return [] if response.first =~ /XX/
+
+        # now we can start building the object
+        loc = Drifter::Location.new
+
+        # Country: UNITED KINGDOM (UK)
+        data = response[0].split(': ').last.split(' (')
+        loc.country = data.first
+        loc.country_code = data.last.sub(')', '')
+        
+        # City: London
+        data = response[1].split(': ').last
+        loc.city = data
+
+        # Latitude: 51.5
+        data = response[2].split(': ').last
+        loc.lat = data.to_f
+
+        # Longitude: -0.1167
+        data = response[3].split(': ').last
+        loc.lng = data.to_f
+
+        return [loc]
+      end
+
+
+      # nodoc
+      def self.query_uri(params)
+        uri = URI.parse(base_uri)
+        uri.query = hash_to_query_string(params)
+        return uri
+      end
+
+
+    end
+
+  end
+end

data/lib/drifter/geocoders/yahoo.rb

@@ -0,0 +1,160 @@
+require 'drifter/geocoders/base'
+module Drifter
+  module Geocoders
+
+    # This class adds support for the Yahoo Placefinder API:
+    # http://developer.yahoo.com/geo/placefinder/
+    #
+    # You must set your appid before using this geocoder:
+    # Drifter::Geocoders::Yahoo.api_key = my_yahoo_appid
+    class Yahoo < Drifter::Geocoders::Base
+
+      YAHOO_BASE_URI = "http://where.yahooapis.com/geocode"
+      @@api_key = nil
+
+
+      # returns the API key (also known as appid) if set, or nil
+      def self.api_key
+        @@api_key
+      end
+
+
+      # sets the api key. Yahoo's API key is known as the appid and
+      # is required for all calls to their Placefinder web service
+      def self.api_key=(value)
+        @@api_key = value
+      end
+
+
+      # nodoc
+      def self.base_uri
+        YAHOO_BASE_URI
+      end
+
+
+      # Geocodes 'location'.  Returns an array of Drifter::Location objects
+      # To geocode a set of coordinates (known as reverse geocoding), you can
+      # pass a two item array containing lat and lng or an object that responds
+      # to lat() and lng(). Examples:
+      #
+      #
+      #   >> Drifter::Geocoders::Yahoo.geocode("Manchester, UK")
+      #   >> Drifter::Geocoders::Yahoo.geocode([52.555, -2.123])
+      #   >> loc = SomeObject.new :lat => 52.555, :lng => -2.123
+      #   >> Drifter::Geocoders::Yahoo.geocode(loc)
+      #
+      #
+      # The returned Drifter::Location objects have the following attributes:
+      #
+      #   :address, :city, :state, :state_code, :country, :country_code,
+      #   :post_code, :lat, :lng
+      #
+      # Any additional data returned by the geocoder can be accessed via the
+      # Location object's data() method
+      #
+      # You can also customise the type of data Yahoo returns by
+      # modifying the 'flags' parameter . e.g if 'flags' contains a T, yahoo
+      # also returns a 'timezone' attribute for the location:
+      #
+      #
+      #   >> results = Drifter::Geocoders::Yahoo.geocode("Manchester, UK", :flags => "T")
+      #   >> results.first.data["timezone"]
+      #   => "Europe/London"
+      #
+      # Yahoo supports other parameters and flags too, see their docs for more details.
+      # http://developer.yahoo.com/geo/placefinder/guide/requests.html
+      def self.geocode(location, params={})
+
+        # set defaults and build the query
+        params[:location] = location
+        params[:flags] ||= 'J'
+
+        # reverse geocoding?
+        lat, lng = Drifter.extract_latlng(location)
+        if lat && lng
+          params[:location] = [lat, lng].join(',')
+          params[:gflags] = params[:gflags].to_s + 'R'
+        end
+
+        check_flags_parameter!(params)
+        uri = query_uri(params)
+        response = fetch(uri)
+
+        # set @@last_error and return nil on error
+        doc = JSON.parse(response)
+        if doc["ResultSet"]["Error"] != 0
+          @@last_error = {
+            :code => doc["ResultSet"]["Error"],
+            :message => doc["ResultSet"]["ErrorMessage"]
+          }
+          return nil
+        end
+
+        # successful so clear any previous errors
+        @@last_error = nil
+
+        # check for results
+        return [] if doc["ResultSet"]["Found"] == 0
+
+        # build and return an array of Drifter::Location objects
+        doc["ResultSet"]["Results"].collect do |result|
+          loc = Drifter::Location.new
+
+          # add all the standard attributes
+          lines = [result["line1"], result["line2"], result["line3"], result["line4"]]
+          lines.delete_if { |line| line.empty? }
+          loc.address = lines.join(', ')
+
+          loc.city = result["city"]
+          loc.state = result["state"]
+          loc.state_code = result["statecode"]
+          loc.country = result["country"]
+          loc.country_code = result["countrycode"]
+          loc.post_code = result["postal"]
+          loc.lat = result["latitude"]
+          loc.lng = result["longitude"]
+
+          # each Location object can also access the raw data if required
+          loc.raw_data = result
+          loc.raw_data_format = :hash
+          loc.geocoder = :yahoo
+          loc
+        end
+
+      end
+
+
+      # returns a URI object after checking that we have an appid and at least one location parameter.
+      # any parameter that the Yahoo placefinder API supports can be passed in params
+      def self.query_uri(params={})
+        # check we have all required parameters
+        check_api_key!
+        uri = URI.parse(base_uri)
+        uri.query = hash_to_query_string(params)
+        return uri
+      end
+
+
+      private
+
+
+      # raises ArgumentError if @@api_key is nil
+      def self.check_api_key!
+        return unless api_key.nil?
+        raise ArgumentError, "API Key (yahoo's appid) is missing!\nPlease set it using #{name}.api_key"
+      end
+
+
+      # geocode() needs responses in JSON format.  If flags contains a P or doesn't
+      # contain a J the response wont be JSON. This method fixes 'bad' flags
+      def self.check_flags_parameter!(params)
+        flags = params[:flags].to_s
+        flags = flags.gsub(/p/i, '')
+        flags << 'J' unless flags.index('J')
+        params[:flags] = flags
+      end
+
+
+    end
+  end
+end

data/lib/drifter/location.rb

@@ -0,0 +1,43 @@
+require 'drifter/location/locatable'
+module Drifter
+  # Drifter.geocode() returns an array of Drifter::Location objects
+  # Depending on the geocoder used, Location objects are populated
+  # with a bunch of common attributes - see the docs for individual
+  # geocoders for a list of attributes they set:
+  #
+  # Drifter::Geocoders::Google.geocode()
+  # Drifter::Geocoders::Yahoo.geocode()
+  #
+  # Additional data returned by the geocoder can be accessed via the
+  # data() method
+  class Location
+    include Drifter::Location::Locatable
+
+    attr_accessor :raw_data
+    attr_accessor :raw_data_format
+    attr_accessor :geocoder
+
+    attr_accessor :address
+    attr_accessor :city
+    attr_accessor :state
+    attr_accessor :state_code
+    attr_accessor :post_code
+    attr_accessor :country
+    attr_accessor :country_code
+    attr_accessor :lat
+    attr_accessor :lng
+
+    # returns a Hash containing the geocoder's raw data. This is geocoder
+    # specific and you should read the provider's docs to see what data
+    # they return in each geocoding response
+    def data
+      @data ||= case raw_data_format
+        when :hash then return raw_data
+        when :json then return JSON.parse(raw_data)
+        else nil
+      end
+    end
+
+
+  end
+end

data/lib/drifter/location/locatable.rb

@@ -0,0 +1,35 @@
+# classes including this module must repond to lat(), lat=(), lng() and lng=()
+module Drifter
+  class Location
+    module Locatable
+
+
+      # nodoc
+      def distance_to(loc, options={})
+        Drifter::Distance::Haversine.between(self, loc, options)
+      end
+
+
+      # returns an empty Drifter:;Location object with lat and lng
+      def location
+        loc = Drifter::Location.new
+        loc.lat = lat
+        loc.lng = lng
+        return loc
+      end
+
+
+      # sets lat and lng on the receiver using value. value can be any 
+      # object that responds to lat() and lng() or a two-item [lat,lng] Array
+      # if value is nil, lat and lng are both set to nil
+      def location=(value)
+        lat, lng = nil, nil
+        lat, lng = Drifter.extract_latlng!(value) unless value.nil?
+        self.lat = lat
+        self.lng = lng
+        return value
+      end
+
+    end
+  end
+end

data/lib/drifter/version.rb

@@ -0,0 +1,3 @@
+module Drifter
+  VERSION = "0.1.0"
+end

data/test/google_geocoder_test.rb

@@ -0,0 +1,85 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+class GoogleGeocoderTest < Test::Unit::TestCase
+
+  def setup
+  end
+
+  # google's raw data isn't a simple key => value hash of address attributes
+  # so we have to do a little digging
+  def attribute_matching(key, data, property=:long_name)
+    data["address_components"].each do |comp|
+      return comp[property.to_s] if comp["types"].include?(key)
+    end
+    return nil
+  end
+
+  # checks that the given Location object has the the expected values when Geocoded using google
+  def assert_google_location(data, loc)
+    assert_equal :google, loc.geocoder
+    assert_equal :hash, loc.raw_data_format
+
+    assert_equal attribute_matching("locality", data), loc.city
+    assert_equal attribute_matching("administrative_area_level_1", data), loc.state
+    assert_equal attribute_matching("postal_code", data), loc.post_code
+    assert_equal attribute_matching("country", data, :short_name), loc.country_code
+    assert_equal data["geometry"]["location"]["lat"], loc.lat
+    assert_equal data["geometry"]["location"]["lng"], loc.lng
+  end
+
+
+  # nodoc
+  def stub_response(response_file)
+    response = open_web_response(response_file)
+    rx = Regexp.new(Drifter::Geocoders::Google.base_uri)
+    FakeWeb.register_uri(:get, rx, :body => response)
+
+    results = Drifter::Geocoders::Google.geocode("springfield")
+    data = JSON.parse(response)
+    error = Drifter::Geocoders::Google.last_error
+
+    return results, data, error
+  end
+
+
+  # nodoc
+  def test_error
+    results, data, error = stub_response('google_error')
+    assert_nil results
+    assert_equal data["status"], error[:message]
+    assert_equal data["status"], error[:code]
+  end
+
+
+  # nodoc
+  def test_success_with_no_results
+    results, data, error = stub_response('google_no_results')
+    assert_nil error
+    assert results.is_a?(Array)
+    assert results.empty?
+  end
+
+
+  # nodoc
+  def test_success_with_one_result
+    results, data, error = stub_response('google_one_result')
+    assert_nil error
+    assert results.is_a?(Array)
+    assert_equal 1, results.size
+    assert_google_location data["results"].first, results.first
+  end
+
+
+  # ndoc
+  def test_success_with_many_results
+    results, data, error = stub_response('google_many_results')
+    assert_nil error
+    assert results.is_a?(Array)
+    assert_equal 10, results.size # this value not returned by google hence hardcoded
+    results.each_with_index do |loc, i|
+      loc_data = data["results"][i]
+      assert_google_location loc_data, loc
+    end
+  end
+
+end