drifter 0.1.0

data/.gitignore

@@ -0,0 +1,3 @@
+pkg/*
+*.gem
+.bundle

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in drifter.gemspec
+gemspec

data/README

@@ -0,0 +1,102 @@
+== drifter
+
+drifter is a simple geocoding library with support for the Google Geocoder API and
+the Yahoo Placefinder API. It also supports IP address geocoding using the hostip.info API
+
+=== Installation
+  
+  gem install drifter
+  require 'rubygems'
+  require 'drifter'
+
+  # if you're using rails:
+  gem install drifter
+  gem 'drifter' # in Gemfile
+
+
+=== Usage
+
+Drifter.geocode() takes a string representing an address or location and returns
+an array of Drifter::Location objects
+
+  >> london = Drifter.geocode("London, UK").first
+  => <#Drifter::Location>
+
+Drifter::Location objects hold common address attributes like city, state, post_code
+country_code, lat and lng:
+
+  >> [london.country_code, london.lat, london.lng]
+  => ['GB', 51.5001524, -0.1262362]
+
+Reverse geocoding is also supported. Instead of passing a string to geocode(), you can
+pass a two item array or an object that responds to lat() and lng()
+
+  >> loc = Drifter.geocode( [53.4807125, -2.2343765] ).first
+  => [loc.city, loc.state].join(', ')
+  => "Manchester, England"
+
+IP address gecoding is supported using the hostip.info api. Just pass the IP as the
+location parameter
+
+  >> loc = Drifter.geocode('1.2.3.4').first
+  => <#Drifter::Location>
+
+hostip.info only provides the city, country, lat and lng. If you need more info, you
+can reverse geocode the result:
+
+  >> loc = Drifter.geocode('1.2.3.4').first
+  >> loc = Drifter.geocode(loc).first
+  >> loc.state_code
+  => 'CA'
+
+Google is the default geocoding provider and works out of the box.  Yahoo's placefinder
+is also supported but you'll need an api key (they call it an appid)
+
+  >> Drifter.default_geocoder = :yahoo
+  >> Drifter::Geocoders::Yahoo.api_key = 'my_key'
+
+  >> bh = Drifter.geocode("90210").first
+  => <#Drifter::Location>
+
+You can change the geocoder per request:
+
+  >> Drifter.geocode("springfield", :geocoder => :yahoo)
+  >> Drifter.geocode("springfield", :geocoder => :google)
+
+Both Yahoo and Google return a lot more info than is held in Drifter::Location's standard
+attributes. You can access the extra data using the data() method which returns a Hash
+
+  # using google as the provider:
+  >> london.data["geometry"]["location_type"]
+  => "APPROXIMATE"
+
+The key => value pairs in the data Hash are specific to each provider, so you'll have to
+check their docs to see what's available.  You can also modify the query sent to the 
+geocoder to customise the results.  Any option other than :geocoder will be URL encoded
+and sent as a query string parameter e.g. Yahoo's service returns a timezone if you pass a
+'flags' parameter containing a 'T':
+
+  >> Drifter.default_geocoder = :yahoo
+  >> paris = Drifter.geocode("Paris", :flags => 'T').first
+  >> paris.data["timezone"]
+  => "Europe/paris"
+
+Finally, Drifter::Location objects have a distance_to() method
+
+  >> london.distance_to(bh)
+  => 5438.60013996461
+
+Distances are returned in miles by default. You can change this per request or change the default
+
+  >> Drifter.default_units = :km
+  >> london.distance_to(bh, :units => :miles)
+
+Drifter.geocode() always returns an array if the request was processed successfully by the
+geocoding service. An empty array indicates that the service returned no results.
+
+If the geocoding service returns an error, Drifter.geocode() returns nil and Drifter.last_error()
+returns a hash with the error :code and :message
+
+=== License
+
+MIT License. Copyright 2011 Ahmed Adam (http://github.com/ahmedrb)

data/README.rdoc

@@ -0,0 +1,102 @@
+== drifter
+
+drifter is a simple geocoding library with support for the Google Geocoder API and
+the Yahoo Placefinder API. It also supports IP address geocoding using the hostip.info API
+
+=== Installation
+  
+  gem install drifter
+  require 'rubygems'
+  require 'drifter'
+
+  # if you're using rails:
+  gem install drifter
+  gem 'drifter' # in Gemfile
+
+
+=== Usage
+
+Drifter.geocode() takes a string representing an address or location and returns
+an array of Drifter::Location objects
+
+  >> london = Drifter.geocode("London, UK").first
+  => <#Drifter::Location>
+
+Drifter::Location objects hold common address attributes like city, state, post_code
+country_code, lat and lng:
+
+  >> [london.country_code, london.lat, london.lng]
+  => ['GB', 51.5001524, -0.1262362]
+
+Reverse geocoding is also supported. Instead of passing a string to geocode(), you can
+pass a two item array or an object that responds to lat() and lng()
+
+  >> loc = Drifter.geocode( [53.4807125, -2.2343765] ).first
+  => [loc.city, loc.state].join(', ')
+  => "Manchester, England"
+
+IP address gecoding is supported using the hostip.info api. Just pass the IP as the
+location parameter
+
+  >> loc = Drifter.geocode('1.2.3.4').first
+  => <#Drifter::Location>
+
+hostip.info only provides the city, country, lat and lng. If you need more info, you
+can reverse geocode the result:
+
+  >> loc = Drifter.geocode('1.2.3.4').first
+  >> loc = Drifter.geocode(loc).first
+  >> loc.state_code
+  => 'CA'
+
+Google is the default geocoding provider and works out of the box.  Yahoo's placefinder
+is also supported but you'll need an api key (they call it an appid)
+
+  >> Drifter.default_geocoder = :yahoo
+  >> Drifter::Geocoders::Yahoo.api_key = 'my_key'
+
+  >> bh = Drifter.geocode("90210").first
+  => <#Drifter::Location>
+
+You can change the geocoder per request:
+
+  >> Drifter.geocode("springfield", :geocoder => :yahoo)
+  >> Drifter.geocode("springfield", :geocoder => :google)
+
+Both Yahoo and Google return a lot more info than is held in Drifter::Location's standard
+attributes. You can access the extra data using the data() method which returns a Hash
+
+  # using google as the provider:
+  >> london.data["geometry"]["location_type"]
+  => "APPROXIMATE"
+
+The key => value pairs in the data Hash are specific to each provider, so you'll have to
+check their docs to see what's available.  You can also modify the query sent to the 
+geocoder to customise the results.  Any option other than :geocoder will be URL encoded
+and sent as a query string parameter e.g. Yahoo's service returns a timezone if you pass a
+'flags' parameter containing a 'T':
+
+  >> Drifter.default_geocoder = :yahoo
+  >> paris = Drifter.geocode("Paris", :flags => 'T').first
+  >> paris.data["timezone"]
+  => "Europe/paris"
+
+Finally, Drifter::Location objects have a distance_to() method
+
+  >> london.distance_to(bh)
+  => 5438.60013996461
+
+Distances are returned in miles by default. You can change this per request or change the default
+
+  >> Drifter.default_units = :km
+  >> london.distance_to(bh, :units => :miles)
+
+Drifter.geocode() always returns an array if the request was processed successfully by the
+geocoding service. An empty array indicates that the service returned no results.
+
+If the geocoding service returns an error, Drifter.geocode() returns nil and Drifter.last_error()
+returns a hash with the error :code and :message
+
+=== License
+
+MIT License. Copyright 2011 Ahmed Adam (http://github.com/ahmedrb)

data/Rakefile

@@ -0,0 +1,8 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+desc "Run tests"
+task :test do
+   path = File.dirname(__FILE__) + '/test/*_test.rb'
+   Dir[path].each { |f| require f }
+end

data/drifter.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "drifter/version"
+
+Gem::Specification.new do |s|
+  s.name        = "drifter"
+  s.version     = Drifter::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Ahmed Adam"]
+  s.homepage    = "http://github.com/ahmedrb/drifter"
+  s.summary     = %q{Simple geocoding library for ruby}
+
+  s.rubyforge_project = "drifter"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_dependency 'json', '~> 1.4.6'
+end

data/lib/drifter.rb

@@ -0,0 +1,92 @@
+require 'rubygems'
+require 'drifter/distance/haversine'
+require 'drifter/geocoders'
+require 'drifter/location'
+
+module Drifter
+
+  @@default_geocoder = :google
+  @@default_units = :miles
+  @@last_error = nil
+
+
+  # returns the default geocoder
+  def self.default_geocoder
+    @@default_geocoder
+  end
+
+
+  # Sets the default geocoder. Supported values are :google or :yahoo
+  # If using :yahoo, you will also need to set your yahoo appid using
+  # Drifter::Geocoders::Yahoo.app_id=()
+  def self.default_geocoder=(value)
+    @@default_geocoder = value
+  end
+
+
+  # Returns the default units for distance calculations
+  def self.default_units
+    @@default_units
+  end
+
+
+  # Sets the default units for distance calculations.
+  # Supported values are :miles and :kms
+  def self.default_units=(value)
+    @@default_units=value
+  end
+
+
+  # Helper method to extract the lat and lng from an array or from any object
+  # that responds to lat() and lng(). Returns nil if neither of those apply
+  def self.extract_latlng(loc)
+    return loc.first, loc.last if loc.is_a?(Array) && loc.size == 2
+    return loc.lat, loc.lng if loc.respond_to?(:lat) && loc.respond_to?(:lng)
+    return nil
+  end
+
+
+  # Same as Drifter,extract_latlng() but raises ArgumentError on failure
+  def self.extract_latlng!(loc)
+    lat, lng = extract_latlng(loc)
+    return lat, lng if lat && lng
+    raise ArgumentError, "Could not extract lat and lng from #{loc.class.name} object"
+  end
+
+
+  # Accepts a string or a set of coordinates and returns an Array of Drifter::Location
+  # objects with the results of the geocoding request.  If there is an error, this
+  # method returns nil and the error can be accessed via Drifter.last_error().
+  #
+  # You can over-ride the default geocoder using the params[:geocoder] option:
+  # Drifter.geocode("somewhere", :geocoder => :yahoo)
+  #
+  # You can perform reverse geocoding by passing a [lat, lng] array, or an object that
+  # responds to lat() and lng().  Any params besides :geocoder are url encoded
+  # and sent to the geocoder as query string parameters.  This can be used to modify
+  # the results of the query. See the README for an example.
+  #
+  # if location is a string containing an IP address, the :geocoder value is ignored
+  # and the ip is geocoded using the hostip.info web service. This only returns a
+  # country, city, lat and lng so you could reverse geocode the result to get more info
+  def self.geocode(location, params={})
+    geocoder = params.delete(:geocoder) || default_geocoder
+    geocoder = :hostip if location.to_s =~ Drifter::Geocoders::HostIP::IP_PATTERN
+    geocoder = case geocoder
+      when :google then Drifter::Geocoders::Google
+      when :yahoo then Drifter::Geocoders::Yahoo
+      when :hostip then Drifter::Geocoders::HostIP
+      else raise ArgumentError, "Geocoder #{geocoder} not recognised"
+    end
+    results = geocoder.geocode(location, params)
+    @@last_error = geocoder.last_error
+    return results
+  end
+
+
+  # Returns a Hash containing error code and status from a failed geocoding request
+  def self.last_error
+    @@last_error
+  end
+
+end

data/lib/drifter/distance/haversine.rb

@@ -0,0 +1,69 @@
+module Drifter
+  module Distance
+    class Haversine
+
+      EarthRadiusInMiles = 3956
+      EarthRadiusInKms = 6371
+      RAD_PER_DEG = 0.017453293  #  PI/180
+
+
+      # this method is from Landon Cox's haversine.rb (GNU Affero GPL v3):
+      # http://www.esawdust.com/blog/gps/files/HaversineFormulaInRuby.html:
+      # http://www.esawdust.com (Landon Cox)
+      # http://www.esawdust.com/blog/businesscard/businesscard.html
+      def self.between(point1, point2, options={})
+        lat1, lon1 = Drifter.extract_latlng!(point1)
+        lat2, lon2 = Drifter.extract_latlng!(point2)
+
+        dlon = lon2 - lon1
+        dlat = lat2 - lat1
+
+        dlon_rad = dlon * RAD_PER_DEG 
+        dlat_rad = dlat * RAD_PER_DEG
+
+        lat1_rad = lat1 * RAD_PER_DEG
+        lon1_rad = lon1 * RAD_PER_DEG
+
+        lat2_rad = lat2 * RAD_PER_DEG
+        lon2_rad = lon2 * RAD_PER_DEG
+
+        a = (Math.sin(dlat_rad/2))**2 + Math.cos(lat1_rad) * Math.cos(lat2_rad) * (Math.sin(dlon_rad/2))**2
+        c = 2 * Math.atan2( Math.sqrt(a), Math.sqrt(1-a))
+
+        units = options.delete(:units) || Drifter.default_units
+        return EarthRadiusInKms * c if units == :km
+        return EarthRadiusInMiles * c
+      end
+
+
+      # haversine sql based on http://code.google.com/apis/maps/articles/phpsqlsearch.html
+      # you will need to add 'select' and 'AS distance' if required
+      def self.to_postgresql(options)
+        origin = options[:origin]
+        lat, lng = Drifter.extract_latlng!(origin)
+        lat_column = options[:lat_column] || :lat
+        lng_column = options[:lng_column] || :lng
+        units = options[:units] || Drifter.default_units
+        multiplier = EarthRadiusInMiles
+        multiplier = EarthRadiusInKms if units == :km
+
+        postgres = <<-EOS
+          #{multiplier} * ACOS(
+            COS( RADIANS(#{lat}) ) *
+            COS( RADIANS( #{lat_column} ) ) *
+            COS( RADIANS( #{lng_column} ) -
+            RADIANS(#{lng}) ) +
+            SIN( RADIANS(#{lat}) ) *
+            SIN( RADIANS( #{lat_column} ) )
+          )
+        EOS
+      end
+
+      # postgresql code seems to work fine fo sql
+      def self.to_mysql(options)
+        to_postgresql(options)
+      end
+
+    end
+  end
+end

data/lib/drifter/geocoders.rb

@@ -0,0 +1,3 @@
+require 'drifter/geocoders/hostip'
+require 'drifter/geocoders/yahoo'
+require 'drifter/geocoders/google'

data/lib/drifter/geocoders/base.rb

@@ -0,0 +1,57 @@
+require 'cgi'
+require 'json'
+require 'net/http'
+require 'uri'
+
+module Drifter
+  module Geocoders
+
+    # nodoc
+    class Base
+
+      @@last_error = nil # used by geocode()
+
+
+      # takes a location parameter and returns an Array of Drifter::Location objects
+      # with the results of the geocoding request.  If the geocoder returns an error,
+      # this method should store the error in @@last_error and return nil.
+      def self.geocode(*args)
+        raise "Not implemented"
+      end
+
+
+      # Returns a Hash containing error information from the last geocoding request
+      # or nil if there was no error. Subclasses should set @@last_error to nil
+      # after every successful request
+      def self.last_error
+        @@last_error
+      end
+
+
+      # Returns a URI object used to make the call to the geocoding service.
+      # Subclasses should implement checks for required parameters. See geocoder/yahoo.rb
+      # for an example
+      def self.query_uri(options={})
+        raise "Not implemented"
+      end
+
+
+      private
+
+
+      # wrapper for Net::HTTP.get
+      def self.fetch(uri)
+        Net::HTTP.get(uri.host, uri.request_uri)
+      end
+
+
+      # Converts hash to a url enoded query string
+      def self.hash_to_query_string(hash)
+        qs = hash.collect{ |k,v| k.to_s + '=' + CGI::escape(v.to_s) }
+        qs.join('&')
+      end
+
+    end
+
+  end
+end