reverse_geocoder 0.0.1

data/History.txt

@@ -0,0 +1,4 @@
+=== 0.0.1 2009-12-06
+
+* 1 major enhancement:
+  * Initial release

data/Manifest.txt

@@ -0,0 +1,26 @@
+History.txt
+Manifest.txt
+README.rdoc
+Rakefile
+lib/reverse_geocoder.rb
+lib/reverse_geocoder/exceptions.rb
+lib/reverse_geocoder/geocoder.rb
+lib/reverse_geocoder/geonames.rb
+lib/reverse_geocoder/google.rb
+lib/reverse_geocoder/ibegin.rb
+lib/reverse_geocoder/multi.rb
+lib/reverse_geocoder/numerex.rb
+lib/reverse_geocoder/version.rb
+script/console
+script/destroy
+script/generate
+spec/geocoder_spec.rb
+spec/geonames_spec.rb
+spec/geoplugin_spec.rb
+spec/google_spec.rb
+spec/ibegin_spec.rb
+spec/multi_spec.rb
+spec/numerex_spec.rb
+spec/spec.opts
+spec/spec_helper.rb
+tasks/rspec.rake

data/README.rdoc

@@ -0,0 +1,70 @@
+= reverse_geocoder
+
+* http://github.com/billeisenhauer/reverse_geocoder
+
+== DESCRIPTION:
+
+Ruby gem containing production-quality reverse geocoding client service.
+
+== FEATURES/PROBLEMS:
+
+Supported reverse geocoders:
+
+- Google
+- Geonames
+- Numerex
+- GeoPlugin
+- iBegin
+
+Failover support provided through the Multi reverse geocoder which is built to
+respect an order preference.  
+
+Exception handling to support query limits exceeded.
+
+== INSTALL:
+
+	sudo gem install reverse_geocoder
+
+== USAGE:
+
+$ ReverseGeocoder::Google.geocode(32.921943,-96.951299, :sensor => true)
+=> {:geocoder=>"Google", :country_code=>"US", :country_name=>"USA", 
+    :address=>"8500 Wellington Point Dr, Irving, TX 75063, USA"}    
+
+Where the return is a Hash and the :address can be used as needed.  
+
+Some exception handling is performed to enable detection of query limit
+issues.  In those cases, rescue ReverseGeocoder::QueryLimitExceeded.
+
+Other exceptions are below, but see the RDOC for more info:
+
+- ReverseGeocoder::AuthenticationError
+- ReverseGeocoder::UnknownServiceError
+- ReverseGeocoder::UnavailableAddress
+- ReverseGeocoder::MalformedRequest
+ 
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009 Bill Eisenhauer
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,26 @@
+require 'rubygems'
+gem 'hoe', '>= 2.1.0'
+require 'hoe'
+require 'fileutils'
+require './lib/reverse_geocoder'
+
+Hoe.plugin :newgem
+# Hoe.plugin :website
+# Hoe.plugin :cucumberfeatures
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.spec 'reverse_geocoder' do
+  self.developer 'FIXME full name', 'FIXME email'
+  self.post_install_message = 'PostInstall.txt' # TODO remove if post-install message not required
+  self.rubyforge_name       = self.name # TODO this is default value
+  # self.extra_deps         = [['activesupport','>= 2.0.2']]
+
+end
+
+require 'newgem/tasks'
+Dir['tasks/**/*.rake'].each { |t| load t }
+
+# TODO - want other tests/tasks run by default? Add them to the list
+# remove_task :default
+# task :default => [:spec, :features]

data/lib/reverse_geocoder.rb

@@ -0,0 +1,15 @@
+require 'rubygems'
+
+gem 'httparty', '>= 0.4.5'
+require 'httparty'
+
+dir = Pathname(__FILE__).dirname.expand_path
+require "#{dir}/reverse_geocoder/version"
+require "#{dir}/reverse_geocoder/exceptions"
+require "#{dir}/reverse_geocoder/geocoder"
+require "#{dir}/reverse_geocoder/google"
+require "#{dir}/reverse_geocoder/geonames"
+require "#{dir}/reverse_geocoder/geoplugin"
+require "#{dir}/reverse_geocoder/ibegin"
+require "#{dir}/reverse_geocoder/numerex"
+require "#{dir}/reverse_geocoder/multi"

data/lib/reverse_geocoder/exceptions.rb

@@ -0,0 +1,20 @@
+module ReverseGeocoder
+  
+  # Exception raised when API key or service credentials are rejected
+  class AuthenticationError < StandardError; end
+  
+  # Exception raised when query limits are exceeded for a service.
+  class QueryLimitExceeded < StandardError; end
+ 
+  # Exception raised when an unknown service error occurs.
+  class UnknownServiceError < StandardError; end
+ 
+  # Exception that is raised when an address is unknown or cannot be returned
+  # for other reasons.
+  class UnavailableAddress < StandardError; end
+  
+  # Exception that is raised when a service query is not understood by the 
+  # service.
+  class MalformedRequest < StandardError; end
+  
+end

data/lib/reverse_geocoder/geocoder.rb

@@ -0,0 +1,104 @@
+module ReverseGeocoder    
+  
+  # This module is meant to be mixed in to a class to enable it to perform
+  # reverse geocoding.  The including class needs to implement three hook
+  # methods:
+  # 
+  # request(lat, lng, options)
+  # normalize(response)
+  # validate_geocoder_options(options)
+  #
+  # The request method uses HTTParty syntax to effect the service call and 
+  # should return its reponse.  Exception handling is not required for the
+  # HTTP response code.
+  #
+  # The normalize method takes the response parameter which behaves like a
+  # Hash and maps it to an expected Hash structure.  As an alternative
+  #
+  # The validate_geocoder_options method is used to validate options provided
+  # to a geocoder.  The geocoder can throw an exception or snuff out the 
+  # options as needed.
+  #
+  module Geocoder   
+    
+    # Mix class methods into the base.
+    def self.included(base) # :nodoc:
+      base.extend(ClassMethods)
+      base.send(:include, HTTParty)
+    end
+    
+    module ClassMethods
+    
+      def geocode(lat, lng, options={})
+        validate_coordinates(lat, lng)
+        validate_options(options)
+        process_request(lat, lng, options)
+      end
+      
+      private
+      
+        ### HOOK METHODS ###
+      
+        # Perform the request from the web service.  This is the only required 
+        # hook method.
+        #
+        def request(lat, lng, options)
+        end
+
+        # Normalize the hash response into a common response so responses are 
+        # common between geocoders.  By default, return the non-normalized 
+        # response if implementers don't wish to perform normalization.
+        # 
+        def normalize(response)
+          response
+        end
+        
+        # Used by geocoders to validate specific options.  If options are
+        # found to be invalid, simply raise an ArgumentError.
+        #
+        def validate_geocoder_options(options)
+        end
+      
+        ### VALIDATION ###
+      
+        def validate_coordinates(lat, lng)
+          if lat.to_f < -90 || lat.to_f > 90
+            raise ArgumentError, "Latitude #{lat} is invalid, try -90 to 90"
+          end
+          if lng.to_f < -180 || lng.to_f > 180
+            raise ArgumentError, "Longitude #{lng} is invalid, try -180 to 180"
+          end          
+        end
+      
+        def validate_options(options)
+          unless options.is_a?(Hash)
+            raise ArgumentError, "Options should be Hash, but is a #{options.class.name}"
+          end
+          validate_geocoder_options(options)
+        end
+        
+        ### REQUEST HANDLING ###
+        
+        def process_request(lat, lng, options={})
+          response = request(lat, lng, options)
+          handle_response(response)
+        end
+        
+        def handle_response(response)
+          case response.code.to_i
+            when 200 
+              normalize(response)
+            when 401..403 
+              raise AuthenticationError 
+            when 404 
+              raise UnavailableAddress
+            else 
+              raise UnknownServiceError
+          end
+        end
+      
+    end
+  
+  end
+  
+end

data/lib/reverse_geocoder/geonames.rb

@@ -0,0 +1,35 @@
+module ReverseGeocoder
+  
+  # Geonames Reverse Geocoder
+  #     
+  class Geonames
+    include ReverseGeocoder::Geocoder
+    
+    base_uri 'http://ws.geonames.org'
+    
+    private
+    
+      def self.request(lat, lng, options)
+        query = {:lat => "#{lat}", :lng => "#{lng}"}.merge(options)
+        get("/findNearestAddress", :query => query)
+      end
+      
+      def self.normalize(response)
+        results = {:geocoder => 'Geonames'}
+        results[:address] = assemble_address_from(response)
+        results[:country_code] = results[:country_name] = response['geonames']['address']['countryCode']
+        results
+      end
+      
+      def self.assemble_address_from(response)
+        address = response['geonames']['address']
+        str =  "#{address['placename']}, "
+        str += "#{address['streetNumber']} #{address['street']}, "
+        str += "#{address['adminName2']}, #{address['adminCode1']}, "
+        str += "#{address['postalcode']}, "
+        str += "#{address['countryCode']}"
+      end
+      
+  end
+  
+end

data/lib/reverse_geocoder/geoplugin.rb

@@ -0,0 +1,29 @@
+module ReverseGeocoder
+  
+  # GeoPlugin Reverse Geocoder
+  #     
+  class GeoPlugin
+    include ReverseGeocoder::Geocoder
+    
+    base_uri 'http://www.geoplugin.net/extras'
+    default_params :format => 'xml'
+    
+    private
+    
+      def self.request(lat, lng, options)
+        query = {:lat => "#{lat}", :long => "#{lng}"}.merge(options)
+        get("/location.gp", :query => query)
+      end
+      
+      def self.normalize(response)
+        results = {:geocoder => 'GeoPlugin'}
+        address = response['geoPlugin']
+        results[:address] = "#{address['geoplugin_place']}, #{address['geoplugin_regionAbbreviated']}, #{address['geoplugin_countryCode']}"
+        results[:country_code] = address['geoplugin_countryCode']
+        results[:country_name] = address['geoplugin_countryCode']
+        results
+      end
+      
+  end
+  
+end

data/lib/reverse_geocoder/google.rb

@@ -0,0 +1,56 @@
+module ReverseGeocoder
+  
+  # Google Reverse Geocoder
+  #     
+  class Google
+    include ReverseGeocoder::Geocoder
+    
+    class << self; attr_accessor :api_key end
+    
+    base_uri 'http://maps.google.com/maps'
+    default_params :key => api_key
+    
+    private
+    
+      def self.request(lat, lng, options)
+        query = {:q => "#{lat},#{lng}"}.merge(options)
+        get("/geo", :query => query)
+      end
+      
+      def self.normalize(response)
+        handle_status(response['Status']['code'])
+        results = {:geocoder => 'Google'}
+        results[:address] = response['Placemark'][0]['address']
+        results[:country_code] = response['Placemark'][0]['AddressDetails']['Country']['CountryNameCode']
+        results[:country_name] = response['Placemark'][0]['AddressDetails']['Country']['CountryName']
+        results
+      end
+      
+      def self.handle_status(status)
+        case status.to_i
+          when 500 
+            raise UnknownServiceError
+          when 601 
+            raise MalformedRequest
+          when 602, 603
+            raise UnavailableAddress
+          when 610 
+            raise AuthenticationError
+          when 620 
+            raise QueryLimitExceeded
+        end
+      end
+      
+      VALID_OPTIONS = [:sensor]
+      
+      def self.validate_geocoder_options(options)
+        options.keys.each do |key|
+          unless VALID_OPTIONS.include?(key)
+            raise ArgumentError, "Options cannot include :#{key}"
+          end
+        end
+      end
+      
+  end
+  
+end

data/lib/reverse_geocoder/ibegin.rb

@@ -0,0 +1,37 @@
+module ReverseGeocoder
+  
+  # iBegin Reverse Geocoder
+  #     
+  class IBegin
+    include ReverseGeocoder::Geocoder
+    
+    class << self; attr_accessor :api_key end
+    
+    base_uri 'http://geocoder.ibegin.com'
+    default_params :apikey => api_key
+    
+    private
+    
+      def self.request(lat, lng, options)
+        query = {:latitude => "#{lat}", :longitude => "#{lng}"}.merge(options)
+        get("/geoxml/", :query => query)
+      end
+      
+      def self.normalize(response)
+        results = {:geocoder => 'iBegin'}
+        address = response['geocode']
+        results[:address] = assemble_address_from(address)
+        results[:country_code] = "US"
+        results[:country_name] = "USA"
+        results
+      end
+      
+      def self.assemble_address_from(address)
+        str =  "#{address['stnumber']} #{address['stname']}, "
+        str += "#{address['stcity']}, #{address['ststate']}, "
+        str += "#{address['stzip']}, US"
+      end
+      
+  end
+  
+end

data/lib/reverse_geocoder/multi.rb

@@ -0,0 +1,21 @@
+module ReverseGeocoder
+  
+  @geocoder_order = [Google, Numerex, Geonames, GeoPlugin]
+  class << self; attr_accessor :geocoder_order end
+  
+  # Multi Reverse Geocoder
+  #     
+  class Multi
+
+    def self.geocode(lat, lng, options={})
+      ReverseGeocoder::geocoder_order.each do |geocoder_class|
+        begin
+          return geocoder_class.send(:geocode, lat, lng, options)
+        rescue
+        end
+      end
+    end
+      
+  end
+  
+end

data/lib/reverse_geocoder/numerex.rb

@@ -0,0 +1,34 @@
+module ReverseGeocoder
+  
+  # Numerex Reverse Geocoder
+  #     
+  class Numerex
+    include ReverseGeocoder::Geocoder
+    
+    base_uri 'http://geo.numerex.com/api/rest/'
+    default_params :function => 'getAddress'
+    
+    private
+    
+      def self.request(lat, lng, options)
+        query = {:lat => "#{lat}", :lon => "#{lng}"}.merge(options)
+        get("/AddressFinder.php", :query => query)
+      end
+      
+      def self.normalize(response)
+        results = {:geocoder => 'Numerex'}
+        address = response['address']
+        results[:address] = assemble_address_from(address)
+        results[:country_code] = ''
+        results[:country_name] = ''
+        results
+      end
+      
+      def self.assemble_address_from(address)
+        str =  address['addr_line1'] + ', '
+        str += address['addr_line2']
+      end
+      
+  end
+  
+end

data/lib/reverse_geocoder/version.rb

@@ -0,0 +1,3 @@
+module ReverseGeocoder #:nodoc:
+  VERSION = '0.0.1'
+end

data/script/console

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# File: script/console
+irb = RUBY_PLATFORM =~ /(:?mswin|mingw)/ ? 'irb.bat' : 'irb'
+
+libs =  " -r irb/completion"
+# Perhaps use a console_lib to store any extra methods I may want available in the cosole
+# libs << " -r #{File.dirname(__FILE__) + '/../lib/console_lib/console_logger.rb'}"
+libs <<  " -r #{File.dirname(__FILE__) + '/../lib/reverse_geocoder.rb'}"
+puts "Loading reverse_geocoder gem"
+exec "#{irb} #{libs} --simple-prompt"

data/script/destroy

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+begin
+  require 'rubigen'
+rescue LoadError
+  require 'rubygems'
+  require 'rubigen'
+end
+require 'rubigen/scripts/destroy'
+
+ARGV.shift if ['--help', '-h'].include?(ARGV[0])
+RubiGen::Base.use_component_sources! [:rubygems, :newgem, :newgem_theme, :test_unit]
+RubiGen::Scripts::Destroy.new.run(ARGV)

data/script/generate

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+begin
+  require 'rubigen'
+rescue LoadError
+  require 'rubygems'
+  require 'rubigen'
+end
+require 'rubigen/scripts/generate'
+
+ARGV.shift if ['--help', '-h'].include?(ARGV[0])
+RubiGen::Base.use_component_sources! [:rubygems, :newgem, :newgem_theme, :test_unit]
+RubiGen::Scripts::Generate.new.run(ARGV)

data/spec/geocoder_spec.rb

@@ -0,0 +1,70 @@
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+class TestGeocoder
+  include ReverseGeocoder::Geocoder
+end
+
+describe 'Geocoder Validations' do
+  
+  it "should reject invalid latitude" do
+    lambda do 
+      TestGeocoder.geocode(180,180) 
+    end.should raise_error(ArgumentError, "Latitude 180 is invalid, try -90 to 90")
+  end
+  
+  it "should reject invalid longitude" do
+    lambda do 
+      TestGeocoder.geocode(0,200) 
+    end.should raise_error(ArgumentError, "Longitude 200 is invalid, try -180 to 180")
+  end
+  
+  it "should reject invalid longitude" do
+    lambda do 
+      TestGeocoder.geocode(90,180, Array.new) 
+    end.should raise_error(ArgumentError, "Options should be Hash, but is a Array")
+  end
+  
+end
+
+describe 'Geocoder Processing' do
+  
+  describe 'valid response' do
+    
+    it 'should return hash response' do
+      response = stub_httparty_response({:status => '200'}, '200')
+      TestGeocoder.stub!(:request).and_return(response)
+      response = TestGeocoder.geocode(90, 180)
+      response.should eql({:status => '200'})
+    end
+    
+  end
+  
+  describe 'with non-200 responses' do
+    
+    it 'should raise an authorization error' do
+      response = stub_httparty_response({}, '401')
+      TestGeocoder.stub!(:request).and_return(response)
+      lambda do 
+        TestGeocoder.geocode(90, 180)
+      end.should raise_error(ReverseGeocoder::AuthenticationError)
+    end
+    
+    it 'should raise an unknown server error' do
+      response = stub_httparty_response({}, '404')
+      TestGeocoder.stub!(:request).and_return(response)
+      lambda do 
+        TestGeocoder.geocode(90, 180)
+      end.should raise_error(ReverseGeocoder::UnavailableAddress)
+    end
+    
+    it 'should raise an unknown server error' do
+      response = stub_httparty_response({}, '500')
+      TestGeocoder.stub!(:request).and_return(response)
+      lambda do 
+        TestGeocoder.geocode(90, 180)
+      end.should raise_error(ReverseGeocoder::UnknownServiceError)
+    end
+    
+  end
+  
+end

data/spec/geonames_spec.rb

@@ -0,0 +1,37 @@
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+describe 'Geonames Geocoder Processing' do
+  
+  describe 'valid response' do
+    
+    valid_response_hash = {
+      'geonames' => {
+        'address' => {
+          'street' => 'Kenwood Dr',
+          'streetNumber' => '598',
+          'postalcode' => '94025',
+          'placename' => 'Menlo Park',
+          'adminName2' => 'San Mateo',
+          'adminCode1' => 'CA',
+          'countryCode' => 'US'
+        }
+      }
+    }
+    
+    normalized_hash = {
+      :geocoder => 'Geonames',
+      :address => 'Menlo Park, 598 Kenwood Dr, San Mateo, CA, 94025, US',
+      :country_code => 'US',
+      :country_name => 'US'
+    }
+    
+    it 'should return normalized data' do
+      response = stub_httparty_response(valid_response_hash, '200')
+      ReverseGeocoder::Geonames.stub!(:request).and_return(response)
+      response = ReverseGeocoder::Geonames.geocode(90, 180)
+      response.should eql(normalized_hash)
+    end
+
+  end
+  
+end

data/spec/geoplugin_spec.rb

@@ -0,0 +1,31 @@
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+describe 'GeoPlugin Geocoder Processing' do
+  
+  describe 'valid response' do
+    
+    valid_response_hash = {
+      'geoPlugin' => {
+        'geoplugin_place' => 'Port Gibson',
+        'geoplugin_countryCode' => 'US',
+        'geoplugin_regionAbbreviated' => 'MS'
+      }
+    }
+    
+    normalized_hash = {
+      :geocoder => 'GeoPlugin',
+      :address => 'Port Gibson, MS, US',
+      :country_code => 'US',
+      :country_name => 'US'
+    }
+    
+    it 'should return normalized data' do
+      response = stub_httparty_response(valid_response_hash, '200')
+      ReverseGeocoder::GeoPlugin.stub!(:request).and_return(response)
+      response = ReverseGeocoder::GeoPlugin.geocode(32, 91)
+      response.should eql(normalized_hash)
+    end
+
+  end
+  
+end

data/spec/google_spec.rb

@@ -0,0 +1,105 @@
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+describe 'Google Geocoder Validations' do
+  
+  it "should reject invalid option" do
+    lambda do 
+      ReverseGeocoder::Google.geocode(90, 180, :invalid => 'invalid') 
+    end.should raise_error(ArgumentError, "Options cannot include :invalid")
+  end
+  
+end
+
+describe 'Google Geocoder Processing' do
+  
+  describe 'valid response' do
+    
+    valid_response_hash = {
+      'name' => '1600 Amphitheatre Parkway, Mountain View, CA',
+      'Status' => {
+        'code' => 200,
+        'request' => 'geocode'
+      },
+      'Placemark' => [
+        {
+          'id' => 'p1',
+          'address' => '1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA',
+          'AddressDetails' => {
+            'Country' => {
+              'CountryNameCode' => 'US',
+              'CountryName' => 'USA'
+            }
+          }
+        }
+      ]
+    }
+    
+    normalized_hash = {
+      :geocoder => 'Google',
+      :address => '1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA',
+      :country_code => 'US',
+      :country_name => 'USA'
+    }
+    
+    it 'should return normalized data' do
+      response = stub_httparty_response(valid_response_hash, '200')
+      ReverseGeocoder::Google.stub!(:request).and_return(response)
+      response = ReverseGeocoder::Google.geocode(90, 180)
+      response.should eql(normalized_hash)
+    end
+    
+  end
+  
+  describe 'with non-200 responses' do
+    
+    it 'should raise a malformed request error' do
+      response = stub_httparty_response({'Status' => {'code' => '500'}}, 200)
+      ReverseGeocoder::Google.stub!(:request).and_return(response)
+      lambda do 
+        ReverseGeocoder::Google.geocode(90, 180)
+      end.should raise_error(ReverseGeocoder::UnknownServiceError)
+    end
+    
+    it 'should raise a malformed request error' do
+      response = stub_httparty_response({'Status' => {'code' => '601'}}, 200)
+      ReverseGeocoder::Google.stub!(:request).and_return(response)
+      lambda do 
+        ReverseGeocoder::Google.geocode(90, 180)
+      end.should raise_error(ReverseGeocoder::MalformedRequest)
+    end
+    
+    it 'should raise a malformed request error' do
+      response = stub_httparty_response({'Status' => {'code' => '602'}}, 200)
+      ReverseGeocoder::Google.stub!(:request).and_return(response)
+      lambda do 
+        ReverseGeocoder::Google.geocode(90, 180)
+      end.should raise_error(ReverseGeocoder::UnavailableAddress)
+    end
+    
+    it 'should raise a malformed request error' do
+      response = stub_httparty_response({'Status' => {'code' => '603'}}, 200)
+      ReverseGeocoder::Google.stub!(:request).and_return(response)
+      lambda do 
+        ReverseGeocoder::Google.geocode(90, 180)
+      end.should raise_error(ReverseGeocoder::UnavailableAddress)
+    end    
+    
+    it 'should raise a malformed request error' do
+      response = stub_httparty_response({'Status' => {'code' => '610'}}, 200)
+      ReverseGeocoder::Google.stub!(:request).and_return(response)
+      lambda do 
+        ReverseGeocoder::Google.geocode(90, 180)
+      end.should raise_error(ReverseGeocoder::AuthenticationError)
+    end
+    
+    it 'should raise a malformed request error' do
+      response = stub_httparty_response({'Status' => {'code' => '620'}}, 200)
+      ReverseGeocoder::Google.stub!(:request).and_return(response)
+      lambda do 
+        ReverseGeocoder::Google.geocode(90, 180)
+      end.should raise_error(ReverseGeocoder::QueryLimitExceeded)
+    end
+    
+  end
+  
+end

data/spec/ibegin_spec.rb

@@ -0,0 +1,33 @@
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+describe 'iBegin Geocoder Processing' do
+  
+  describe 'valid response' do
+    
+    valid_response_hash = {
+      'geocode' => {
+        'stcity' => 'Washington',
+        'ststate' => 'DC',
+        'stzip' => '20502',
+        'stnumber' => '1610',
+        'stname' => 'Pennsylvania Ave'
+      }
+    }
+    
+    normalized_hash = {
+      :geocoder => 'iBegin',
+      :address => '1610 Pennsylvania Ave, Washington, DC, 20502, US',
+      :country_code => 'US',
+      :country_name => 'USA'
+    }
+    
+    it 'should return normalized data' do
+      response = stub_httparty_response(valid_response_hash, '200')
+      ReverseGeocoder::IBegin.stub!(:request).and_return(response)
+      response = ReverseGeocoder::IBegin.geocode(38.898747, -77.037947)
+      response.should eql(normalized_hash)
+    end
+
+  end
+  
+end

data/spec/multi_spec.rb

@@ -0,0 +1,42 @@
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+describe 'Multi Geocoder' do
+  
+  it "should contain a list of geocoder providers" do
+    geocoder_order = [
+      ReverseGeocoder::Google, 
+      ReverseGeocoder::Numerex, 
+      ReverseGeocoder::Geonames, 
+      ReverseGeocoder::GeoPlugin
+    ]
+    ReverseGeocoder.geocoder_order.should eql(geocoder_order)
+  end
+  
+  google_normalized_hash = {
+    :geocoder => 'Google',
+    :address => '1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA',
+    :country_code => 'US',
+    :country_name => 'USA'
+  }
+  
+  numerex_normalized_hash = {
+    :geocoder => 'Numerex',
+    :address => '8513 Wellington Point Dr, Irving, TX 75063',
+    :country_code => '',
+    :country_name => ''
+  }
+  
+  it 'should call the first geocoder provider' do
+    ReverseGeocoder::Google.stub!(:geocode).and_return(google_normalized_hash)
+    response = ReverseGeocoder::Multi.geocode(90, 180)
+    response.should eql(google_normalized_hash)
+  end
+
+  it 'should fail over to the second geocoder provider' do
+    ReverseGeocoder::Google.stub!(:geocode).and_raise(ReverseGeocoder::QueryLimitExceeded)
+    ReverseGeocoder::Numerex.stub!(:geocode).and_return(numerex_normalized_hash)
+    response = ReverseGeocoder::Multi.geocode(90, 180)
+    response.should eql(numerex_normalized_hash)
+  end
+  
+end

data/spec/numerex_spec.rb

@@ -0,0 +1,30 @@
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+describe 'Numerex Geocoder Processing' do
+  
+  describe 'valid response' do
+    
+    valid_response_hash = {
+      'address' => {
+        'addr_line1' => '8513 Wellington Point Dr',
+        'addr_line2' => 'Irving, TX 75063'
+      }
+    }
+    
+    normalized_hash = {
+      :geocoder => 'Numerex',
+      :address => '8513 Wellington Point Dr, Irving, TX 75063',
+      :country_code => '',
+      :country_name => ''
+    }
+    
+    it 'should return normalized data' do
+      response = stub_httparty_response(valid_response_hash, '200')
+      ReverseGeocoder::Numerex.stub!(:request).and_return(response)
+      response = ReverseGeocoder::Numerex.geocode(32.9219569943518, -96.9514012365146)
+      response.should eql(normalized_hash)
+    end
+
+  end
+  
+end

data/spec/spec.opts

@@ -0,0 +1 @@
+--colour

data/spec/spec_helper.rb

@@ -0,0 +1,19 @@
+begin
+  require 'spec'
+rescue LoadError
+  require 'rubygems' unless ENV['NO_RUBYGEMS']
+  gem 'rspec'
+  require 'spec'
+end
+
+$:.unshift(File.dirname(__FILE__) + '/../lib')
+require 'reverse_geocoder'
+
+
+Spec::Runner.configure do |config|
+  
+  def stub_httparty_response(response_object, code)
+    HTTParty::Response.new(response_object, '', code, 'OK')
+  end
+
+end

data/tasks/rspec.rake

@@ -0,0 +1,21 @@
+begin
+  require 'spec'
+rescue LoadError
+  require 'rubygems' unless ENV['NO_RUBYGEMS']
+  require 'spec'
+end
+begin
+  require 'spec/rake/spectask'
+rescue LoadError
+  puts <<-EOS
+To use rspec for testing you must install rspec gem:
+    gem install rspec
+EOS
+  exit(0)
+end
+
+desc "Run the specs under spec/models"
+Spec::Rake::SpecTask.new do |t|
+  t.spec_opts = ['--options', "spec/spec.opts"]
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification 
+name: reverse_geocoder
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Bill Eisenhauer
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-12-06 00:00:00 -06:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.3.3
+    version: 
+description: ReverseGeocoder Gem
+email: 
+- bill@billeisenhauer.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- README.rdoc
+files: 
+- History.txt
+- Manifest.txt
+- README.rdoc
+- Rakefile
+- lib/reverse_geocoder.rb
+- lib/reverse_geocoder/exceptions.rb
+- lib/reverse_geocoder/geocoder.rb
+- lib/reverse_geocoder/geonames.rb
+- lib/reverse_geocoder/geoplugin.rb
+- lib/reverse_geocoder/google.rb
+- lib/reverse_geocoder/ibegin.rb
+- lib/reverse_geocoder/multi.rb
+- lib/reverse_geocoder/numerex.rb
+- lib/reverse_geocoder/version.rb
+- script/console
+- script/destroy
+- script/generate
+- spec/geocoder_spec.rb
+- spec/geonames_spec.rb
+- spec/geoplugin_spec.rb
+- spec/google_spec.rb
+- spec/ibegin_spec.rb
+- spec/multi_spec.rb
+- spec/numerex_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+- tasks/rspec.rake
+has_rdoc: true
+homepage: http://github.com/billeisenhauer/reverse_geocoder
+licenses: []
+
+post_install_message: PostInstall.txt
+rdoc_options: 
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: reverse_geocoder
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Ruby gem containing production-quality reverse geocoding client service.
+test_files: []
+