Retreive the geolocation of an IP address based on the ipinfodb.com webservice
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib
spec Locked rspec version to 3 and removed typo Mar 2, 2018
.gitignore Removes Gemfile.lock from repository Sep 18, 2015
.rubocop.yml Adds rubocop config with a todo Sep 18, 2015
.rubocop_todo.yml
.travis.yml Adds ruby 2.3, 2.4 and 2.5 to the build matrix Feb 26, 2018
CHANGES.md Bumps version to v0.7.1 Aug 20, 2018
Gemfile Switches to bundler for gem deployment Mar 26, 2011
LICENSE Updates copyright years to 2018 Aug 20, 2018
README.md Updates copyright years to 2018 Aug 20, 2018
Rakefile Enables rubocop Style/StringLiterals and fixes related offence Sep 18, 2015
geo_ip.gemspec Bumps version to v0.7.1 Aug 20, 2018
init.rb Implemented initial state of geo_ip Jan 9, 2010

README.md

GeoIp

Retreive the geolocation of an IP address based on the ipinfodb.com webservice.

As of 8th November 2010, the service is asking that all users register for an API key.

Consider making a donation to ipinfodb.com at 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:

GeoIp.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

note: As of v0.6.0 GeoIp is only compatible with ruby 1.9.3 or higher. You can still use v0.5.0 if you need ruby 1.8.7 or 1.9.2 compatiblity.

Rails

Bundler enabled (Rails 3.x and 2.3.x)

In your Gemfile:

gem 'geo_ip'

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'

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

Bugs

Please report them on the Github issue tracker for this project.

If you have a bug to report, please include the following information:

  • Version information for geo_ip, ruby and/or rails.
  • 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-2018 Jeroen Jacobs. See LICENSE for details.