geo_ip 0.4.0 → 0.5.0

data/CHANGES.md

@@ -0,0 +1,40 @@
+## 0.5.0
+
+* Wrap Ruby's Timeout module around the RestClient call to enforce timeout if caused by bad internet connection or slow or invalid DNS lookup. Added WebMock to tests to have reliable tests. By [harleyttd](https://github.com/harleyttd)
+
+## 0.4.0
+
+* Uses API v3
+
+## 0.3.2
+
+* Switches to [rest-client](https://github.com/adamwiggins/rest-client) for requests
+* Sets default timeout to 1 second and adds option to override it
+* More relaxed json dependency scoping
+* Some internal code refactoring
+
+## 0.3.1
+
+* Switches to bundler for gem deployment
+* Uses Rspec 2.x from now on
+
+## 0.3.0
+
+* Added support for API key requirement (Thanks to seanconaty and luigi)
+* Explicit gem dependency for json and removed rubygems requirement (idris) (http://tomayko.com/writings/require-rubygems-antipattern)
+* Removed deprecated GeoIp#remote_geolocation method
+
+## 0.2.0
+
+* Added support for timezone information. Use the optional {:timezone => true|false} option
+* Added support for country lookup. This will result in a faster reply since less queries need
+  to be done at ipinfodb's side. Use the optional {:precision => :city|:country} option
+* API change: GeoIp.remote_geolocation(ip) is deprecated in favor of GeoIp.geolocation(ip)
+
+## 0.1.1
+
+* Removed time zone information since this has been deprecated with the service
+
+## 0.1.0
+
+* Initial commit

data/README.md

@@ -0,0 +1,167 @@
+# GeoIp
+
+Retreive the geolocation of an IP address based on the [ipinfodb.com](http://ipinfodb.com/) webservice.
+
+As of 8th November 2010, the service is asking that all users [register](http://ipinfodb.com/register.php) for an API key.
+
+Consider making a donation to [ipinfodb.com](http://ipinfodb.com/) at [http://ipinfodb.com/donate.php](http://ipinfodb.com/donate.php).
+
+## Usage
+
+### Set API key
+    GeoIp.api_key = 'YOUR_API_KEY'
+
+This must be done before making the geolocation call.
+
+### Retrieve geolocation
+    GeoIp.geolocation(ip_address)
+
+### Example
+
+    # 209.85.227.104 = google.be (US)
+    GeoIp.geolocation('209.85.227.104')
+
+returns:
+
+    {
+      :status_code    => "OK",
+      :status_message => "",
+      :ip             => "209.85.227.104"
+      :country_code   => "US",
+      :country_name   => "UNITED STATES",
+      :region_name    => "CALIFORNIA",
+      :city           => "MONTEREY PARK",
+      :zip_code       => "91754",
+      :latitude       => "34.0505",
+      :longitude      => "-118.13"
+    }
+
+### Country only
+
+There is an option to only retreive the country information and thus excluding the city details. This results in a faster response from the service since less queries need to be done.
+
+    GeoIp.geolocation('209.85.227.104', :precision => :country)
+
+returns:
+
+    {
+      :status_code    => "OK",
+      :status_message => "",
+      :ip             => "209.85.227.104"
+      :country_code   => "US",
+      :country_name   => "UNITED STATES"
+    }
+
+### Timezone information
+
+There is an option now to retrieve optional timezone information too:
+
+    GeoIp.geolocation('209.85.227.104', :timezone => true)
+
+returns:
+
+    {
+      :status_code    => "OK",
+      :status_message => "",
+      :ip             => "209.85.227.104"
+      :country_code   => "US",
+      :country_name   => "UNITED STATES",
+      :region_name    => "CALIFORNIA",
+      :city           => "MONTEREY PARK",
+      :zip_code       => "91754",
+      :latitude       => "34.0505",
+      :longitude      => "-118.13"
+      :timezone       => "-08:00"
+    }
+
+Obviously it is not possible to have the country precision enabled while retrieving the timezone information.
+
+### Reserved / Private / Local IPs
+
+Passing reserved, private or local IPs, such as `127.0.0.1` will return `-` for all location data, for example:
+
+    GeoIpCurb.geolocation('127.0.0.1')
+
+returns:
+
+    {
+      :status_code    => "OK",
+      :status_message => "",
+      :ip             => "127.0.0.1",
+      :country_code   => "-",
+      :country_name   => "-",
+      :region_name    => "-",
+      :city           => "-",
+      :zip_code       => "-",
+      :latitude       => "0",
+      :longitude      => "0"
+    }
+
+### Timeout
+
+It is possible to set a timeout for all requests. By default it is one second, but you can easily set a different value. Just like you would set the api_key you can set the timeout:
+
+    GeoIp.timeout = 5 # In order to set it to five seconds
+
+## Getting it
+
+GeoIp can be installed as a Ruby Gem:
+
+    gem install geo_ip
+
+### Rails
+
+#### Bundler enabled (Rails 3.0.x and 2.3.x)
+
+In your Gemfile:
+
+    gem 'geo_ip', '~> 0.3.0'
+
+Then create an initializer `config/initializers/geo_ip` (or name it whatever you want):
+
+    GeoIp.api_key = 'YOUR_API_KEY'
+
+#### Pre-bundler (Rails 2.3.x or older)
+
+In your `config/environment.rb`:
+
+    config.gem 'geo_ip', :version => '~> 0.3.0'
+
+Then create an initializer `config/initializers/geo_ip` (or name it whatever you want):
+
+    GeoIp.api_key = 'YOUR_API_KEY'
+
+## Testing
+
+Set up your API key first for the test suite by creating a spec/api.yml file. Follow the example in spec/api.yml.example. Then run the tests with:
+
+    ruby spec/geo_ip_spec.rb
+
+If you get a LoadError, you should run the tests with:
+
+    ruby -rubygems spec/geo_ip_spec.rb
+
+## Contributors
+
+* [seanconaty](https://github.com/seanconaty)
+* [luigi](https://github.com/luigi)
+* [idris](https://github.com/idris)
+* [Rylon](https://github.com/Rylon)
+* [harleyttd](https://github.com/harleyttd)
+
+## Bugs
+
+Please report them on the [Github issue tracker](https://github.com/jeroenj/geo_ip/issues)
+for this project.
+
+If you have a bug to report, please include the following information:
+
+* **Version information for bierdopje, Rails and Ruby.**
+* Stack trace and error message.
+
+You may also fork this project on Github and create a pull request.
+Do not forget to include tests.
+
+## Copyright
+
+Copyright (c) 2010-2011 Jeroen Jacobs. See LICENSE for details.

data/lib/geo_ip.rb

@@ -9,6 +9,7 @@ class GeoIp
 
   @@api_key = nil
   @@timeout = 1
+  @@fallback_timeout = 3
 
   class << self
     def api_key
@@ -27,6 +28,29 @@ class GeoIp
       @@timeout = timeout
     end
 
+    def fallback_timeout
+      @@fallback_timeout
+    end
+
+    def fallback_timeout= fallback_timeout
+      @@fallback_timeout = fallback_timeout
+    end
+
+    def set_defaults_if_necessary options
+      options[:precision] ||= :city
+      options[:timezone]  ||= false
+      raise 'Invalid precision'  unless [:country, :city].include?(options[:precision])
+      raise 'Invalid timezone'   unless [true, false].include?(options[:timezone])
+    end
+
+    def lookup_url ip, options = {}
+      set_defaults_if_necessary options
+      raise 'API key must be set first: GeoIp.api_key = \'YOURKEY\'' if self.api_key.nil?
+      raise 'Invalid IP address' unless ip.to_s =~ IPV4_REGEXP
+
+      "#{SERVICE_URL}#{options[:precision] == :city || options[:timezone] ? CITY_API : COUNTRY_API}?key=#{api_key}&ip=#{ip}&format=json&timezone=#{options[:timezone]}"
+    end
+
     # Retreive the remote location of a given ip address.
     #
     # It takes two optional arguments:
@@ -36,32 +60,31 @@ class GeoIp
     # ==== Example:
     #   GeoIp.geolocation('209.85.227.104', {:precision => :city, :timezone => true})
     def geolocation ip, options={}
-      @precision = options[:precision] || :city
-      @timezone  = options[:timezone]  || false
-      raise 'API key must be set first: GeoIp.api_key = \'YOURKEY\'' if self.api_key.nil?
-      raise 'Invalid IP address' unless ip.to_s =~ IPV4_REGEXP
-      raise 'Invalid precision'  unless [:country, :city].include?(@precision)
-      raise 'Invalid timezone'   unless [true, false].include?(@timezone)
-      url = "#{SERVICE_URL}#{@precision == :city || @timezone ? CITY_API : COUNTRY_API}?key=#{api_key}&ip=#{ip}&format=json&timezone=#{@timezone}"
-      parsed_response = JSON.parse RestClient::Request.execute(:method => :get, :url => url, :timeout => self.timeout)
-      convert_keys parsed_response
+      location = nil
+      Timeout.timeout(self.fallback_timeout) do
+        parsed_response = JSON.parse RestClient::Request.execute(:method => :get, :url => lookup_url(ip, options), :timeout => self.timeout)
+        location = convert_keys(parsed_response, options)
+      end
+
+      location
     end
 
     private
-    def convert_keys hash
+    def convert_keys hash, options
+      set_defaults_if_necessary options
       location = {}
       location[:ip]             = hash['ipAddress']
       location[:status_code]    = hash['statusCode']
       location[:status_message] = hash['statusMessage']
       location[:country_code]   = hash['countryCode']
       location[:country_name]   = hash['countryName']
-      if @precision == :city
+      if options[:precision] == :city
         location[:region_name]  = hash['regionName']
         location[:city]         = hash['cityName']
         location[:zip_code]     = hash['zipCode']
         location[:latitude]     = hash['latitude']
         location[:longitude]    = hash['longitude']
-        if @timezone
+        if options[:timezone]
           location[:timezone]   = hash['timeZone']
         end
       end

data/spec/geo_ip_spec.rb

@@ -2,8 +2,27 @@ require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
 IP_GOOGLE_US = '209.85.227.104'
 IP_PRIVATE = '10.0.0.1'
 IP_LOCAL = '127.0.0.1'
+# Use WebMock as default to speed up tests and for local development without a connection
+# Change this to false to have tests make real http requests if you want. Perhaps to check whether IpInfoDb's API has changed
+# However, you may need to increase the GeoIp.fallback_timeout variable if Timeout exceptions occur when tests are run
+USE_WEBMOCK = true
 
 describe 'GeoIp' do
+  before :all do
+    unless USE_WEBMOCK
+      puts "Running tests WITHOUT WebMock. You will need an internet connection. You may need to increase the GeoIp.fallback_timeout amount."
+      WebMock.disable!
+    end
+  end
+
+  def stub_geolocation(ip, options = {}, &block)
+    if USE_WEBMOCK
+      stub_request(:get, GeoIp.lookup_url(ip, options)).
+             with(:headers => {'Accept'=>'*/*; q=0.5, application/xml', 'Accept-Encoding'=>'gzip, deflate'}).
+             to_return(:status => 200, :body => yield, :headers => {})
+    end
+  end
+
   before :each do
     api_config = YAML.load_file(File.dirname(__FILE__) + '/api.yml')
     GeoIp.api_key = api_config['key']
@@ -23,6 +42,22 @@ describe 'GeoIp' do
 
   context 'city' do
     it 'should return the correct city for a public ip address' do
+      stub_geolocation(IP_GOOGLE_US) do
+%[{
+              "statusCode" : "OK",
+              "statusMessage" : "",
+              "ipAddress" : "209.85.227.104",
+              "countryCode" : "US",
+              "countryName" : "UNITED STATES",
+              "regionName" : "CALIFORNIA",
+              "cityName" : "MONTEREY PARK",
+              "zipCode" : "91754",
+              "latitude" : "34.0505",
+              "longitude" : "-118.13",
+              "timeZone" : "-08:00"
+}]
+      end
+
       geolocation = GeoIp.geolocation(IP_GOOGLE_US)
       geolocation[:country_code].should == 'US'
       geolocation[:country_name].should == 'UNITED STATES'
@@ -30,6 +65,22 @@ describe 'GeoIp' do
     end
 
     it 'should return nothing city for a private ip address' do
+      stub_geolocation(IP_PRIVATE) do
+%[{
+              "statusCode" : "OK",
+              "statusMessage" : "",
+              "ipAddress" : "10.0.0.1",
+              "countryCode" : "-",
+              "countryName" : "-",
+              "regionName" : "-",
+              "cityName" : "-",
+              "zipCode" : "-",
+              "latitude" : "0",
+              "longitude" : "0",
+              "timeZone" : "-"
+}]
+      end
+
       geolocation = GeoIp.geolocation(IP_PRIVATE)
       geolocation[:country_code].should == '-'
       geolocation[:country_name].should == '-'
@@ -37,6 +88,22 @@ describe 'GeoIp' do
     end
 
     it 'should return nothing for localhost ip address' do
+      stub_geolocation(IP_LOCAL) do
+%[{
+	"statusCode" : "OK",
+	"statusMessage" : "",
+	"ipAddress" : "127.0.0.1",
+	"countryCode" : "-",
+	"countryName" : "-",
+	"regionName" : "-",
+	"cityName" : "-",
+	"zipCode" : "-",
+	"latitude" : "0",
+	"longitude" : "0",
+	"timeZone" : "-"
+}]
+      end
+
       geolocation = GeoIp.geolocation(IP_LOCAL)
       geolocation[:country_code].should == '-'
       geolocation[:country_name].should == '-'
@@ -44,6 +111,22 @@ describe 'GeoIp' do
     end
 
     it 'should return the correct city for a public ip address when explicitly requiring it' do
+      stub_geolocation(IP_GOOGLE_US) do
+%[{
+	"statusCode" : "OK",
+	"statusMessage" : "",
+	"ipAddress" : "209.85.227.104",
+	"countryCode" : "US",
+	"countryName" : "UNITED STATES",
+	"regionName" : "CALIFORNIA",
+	"cityName" : "MONTEREY PARK",
+	"zipCode" : "91754",
+	"latitude" : "34.0505",
+	"longitude" : "-118.13",
+	"timeZone" : "-08:00"
+}]
+      end
+
       geolocation = GeoIp.geolocation(IP_GOOGLE_US, :precision => :city)
       geolocation[:country_code].should == 'US'
       geolocation[:country_name].should == 'UNITED STATES'
@@ -53,24 +136,60 @@ describe 'GeoIp' do
 
   context 'country' do
     it 'should return the correct country for a public ip address' do
+      stub_geolocation(IP_GOOGLE_US, :precision => :country) do
+%[{
+	"statusCode" : "OK",
+	"statusMessage" : "",
+	"ipAddress" : "209.85.227.104",
+	"countryCode" : "US",
+	"countryName" : "UNITED STATES"
+}]
+      end
       geolocation = GeoIp.geolocation(IP_GOOGLE_US, :precision => :country)
       geolocation[:country_code].should == 'US'
       geolocation[:country_name].should == 'UNITED STATES'
     end
 
     it 'should return nothing country for a private ip address' do
+      stub_geolocation(IP_PRIVATE, :precision => :country) do
+%[{
+	"statusCode" : "OK",
+	"statusMessage" : "",
+	"ipAddress" : "10.0.0.1",
+	"countryCode" : "-",
+	"countryName" : "-"
+}]
+      end
       geolocation = GeoIp.geolocation(IP_PRIVATE, :precision => :country)
       geolocation[:country_code].should == '-'
       geolocation[:country_name].should == '-'
     end
 
     it 'should return nothing country for localhost ip address' do
+      stub_geolocation(IP_LOCAL, :precision => :country) do
+%[{
+	"statusCode" : "OK",
+	"statusMessage" : "",
+	"ipAddress" : "127.0.0.1",
+	"countryCode" : "-",
+	"countryName" : "-"
+}]
+      end
       geolocation = GeoIp.geolocation(IP_LOCAL, :precision => :country)
       geolocation[:country_code].should == '-'
       geolocation[:country_name].should == '-'
     end
 
     it 'should not return the city for a public ip address' do
+      stub_geolocation(IP_GOOGLE_US, :precision => :country) do
+%[{
+	"statusCode" : "OK",
+	"statusMessage" : "",
+	"ipAddress" : "209.85.227.104",
+	"countryCode" : "US",
+	"countryName" : "UNITED STATES"
+}]
+      end
       geolocation = GeoIp.geolocation(IP_GOOGLE_US, :precision => :country)
       geolocation[:country_code].should == 'US'
       geolocation[:country_name].should == 'UNITED STATES'
@@ -80,23 +199,96 @@ describe 'GeoIp' do
 
   context 'timezone' do
     it 'should return the correct timezone information for a public ip address' do
+      stub_geolocation(IP_GOOGLE_US, :timezone => true) do
+%[{
+	"statusCode" : "OK",
+	"statusMessage" : "",
+	"ipAddress" : "209.85.227.104",
+	"countryCode" : "US",
+	"countryName" : "UNITED STATES",
+	"regionName" : "CALIFORNIA",
+	"cityName" : "MONTEREY PARK",
+	"zipCode" : "91754",
+	"latitude" : "34.0505",
+	"longitude" : "-118.13",
+	"timeZone" : "-08:00"
+}]
+      end
       geolocation = GeoIp.geolocation(IP_GOOGLE_US, :timezone => true)
       geolocation[:timezone].should == '-08:00' # This one is likely to break when dst changes.
     end
 
     it 'should not return the timezone information when explicitly not requesting it' do
+      stub_geolocation(IP_GOOGLE_US, :timezone => false) do
+%[{
+	"statusCode" : "OK",
+	"statusMessage" : "",
+	"ipAddress" : "209.85.227.104",
+	"countryCode" : "US",
+	"countryName" : "UNITED STATES",
+	"regionName" : "CALIFORNIA",
+	"cityName" : "MONTEREY PARK",
+	"zipCode" : "91754",
+	"latitude" : "34.0505",
+	"longitude" : "-118.13",
+	"timeZone" : "-08:00"
+}]
+      end
       geolocation = GeoIp.geolocation(IP_GOOGLE_US, :timezone => false)
       geolocation[:timezone].should be_nil
     end
 
     it 'should not return the timezone information when not requesting it' do
+      stub_geolocation(IP_GOOGLE_US) do
+%[{
+	"statusCode" : "OK",
+	"statusMessage" : "",
+	"ipAddress" : "209.85.227.104",
+	"countryCode" : "US",
+	"countryName" : "UNITED STATES",
+	"regionName" : "CALIFORNIA",
+	"cityName" : "MONTEREY PARK",
+	"zipCode" : "91754",
+	"latitude" : "34.0505",
+	"longitude" : "-118.13",
+	"timeZone" : "-08:00"
+}]
+      end
       geolocation = GeoIp.geolocation(IP_GOOGLE_US)
       geolocation[:timezone].should be_nil
     end
 
     it 'should not return the timezone information when country precision is selected' do
+      stub_geolocation(IP_GOOGLE_US, :precision => :country, :timezone => true) do
+%[{
+	"statusCode" : "OK",
+	"statusMessage" : "",
+	"ipAddress" : "209.85.227.104",
+	"countryCode" : "US",
+	"countryName" : "UNITED STATES",
+	"regionName" : "CALIFORNIA",
+	"cityName" : "MONTEREY PARK",
+	"zipCode" : "91754",
+	"latitude" : "34.0505",
+	"longitude" : "-118.13",
+	"timeZone" : "-08:00"
+}]
+      end
       geolocation = GeoIp.geolocation(IP_GOOGLE_US, :precision => :country, :timezone => true)
       geolocation[:timezone].should be_nil
     end
   end
+
+  context "timeout" do
+    it 'should trigger timeout when the request is taking too long' do
+      stub_request(:get, GeoIp.lookup_url(IP_GOOGLE_US)).to_timeout
+      lambda { GeoIp.geolocation(IP_GOOGLE_US) }.should raise_exception("Request Timeout")
+    end
+
+    it 'should trigger fallback timeout when RestClient is taking too long to send the request', :focus => true do
+      GeoIp.fallback_timeout = 1
+      RestClient::Request.stub(:execute) { sleep 1 }
+      lambda { GeoIp.geolocation(IP_GOOGLE_US) }.should raise_exception(Timeout::Error)
+    end
+  end
 end

data/spec/spec_helper.rb

@@ -1,3 +1,4 @@
 require 'rubygems'
 require 'bundler/setup'
 require 'geo_ip'
+require 'webmock/rspec'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: geo_ip
 version: !ruby/object:Gem::Version 
-  hash: 15
+  hash: 11
   prerelease: 
   segments: 
   - 0
-  - 4
+  - 5
   - 0
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors: 
 - Jeroen Jacobs
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-29 00:00:00 +02:00
+date: 2012-03-03 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -50,9 +50,23 @@ dependencies:
   type: :runtime
   version_requirements: *id002
 - !ruby/object:Gem::Dependency 
-  name: rspec
+  name: rake
   prerelease: false
   requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -63,7 +77,23 @@ dependencies:
         - 5
         version: "2.5"
   type: :development
-  version_requirements: *id003
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: webmock
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 31
+        segments: 
+        - 1
+        - 7
+        - 10
+        version: 1.7.10
+  type: :development
+  version_requirements: *id005
 description: A call to the ipinfodb.com will be done to retreive the geolocation based on the IP address. No need to include a database file in the application.
 email: gems@jeroenj.be
 executables: []
@@ -73,6 +103,8 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
+- README.md
+- CHANGES.md
 - LICENSE
 - lib/geo_ip.rb
 - spec/api.yml