EasyGeoIP

Note: No longer actively maintained!

A common Ruby interface to retrieve IP-based geolocation information from various free and open source IP geolocation services.

No database downloads, no registration, no API keys, no minimal dependencies. Easy!

Quick Example

EasyGeoIP.query("8.8.8.8")

# => #<EasyGeoIP::GeoData:0x007f91b9512960
 @city="Mountain View",
 @continent_code="NA",
 @country="United States",
 @country_code="US",
 @ip="8.8.8.8",
 @isp="Google Inc.",
 @latitude=37.386,
 @longitude=-122.0838,
 @postal_code="94040",
 @region="California",
 @region_code="CA",
 @time_zone="America/Los_Angeles">

EasyGeoIP.query("2001:4860:4860::8888")

See the 'Usage' section for more information.

IP Geolocation Services

EasyGeoIP currently supports the geolocation services listed below. All of these services are free, open source, and require no registration or authentication.

Regardless of which service is used, geolocation information is returned in the same format for ease of use. See the EasyGeoIP::GeoData section below for more information.

Freegeoip (Default) :freegeoip

• HTTPS: Yes
• Limits: 10,000 queries per hour
• Open Source License: BSD 3-clause
• GitHub Project: https://www.github.com/fiorix/freegeoip
• Homepage: https://www.freegeoip.net

Nekudo :nekudo

• HTTPS: No
• Limits: None, but fair use policy applies
• Open Source License: MIT
• GitHub Project: https://www.github.com/nekudo/shiny_geoip
• Homepage: http://geoip.nekudo.com

Telize :telize

• HTTPS: Yes
• Limits: None
• Open Source License: MIT
• GitHub Project: https://www.github.com/fcambus/telize
• Homepage: http://www.telize.com

Note: Telize's public API has been discontinued.

All of the above services use data provided by MaxMind.

Reliability

The services listed above are free, require no registration, and are supported by volunteer developers. It is generally understood that such services are traditionally more likely to experience downtime or disruption.

If IP geolocation is mission-critical in your application, consider using a paid commercial service to mitigate the risk of downtime and disruption.

Installation

Add this line to your application's Gemfile:

gem "easy_geoip"

And then execute:

$ bundle

Or install it yourself as:

$ gem install easy_geoip

Supported Ruby versions

EasyGeoIP supports MRI Ruby 1.9+ and the JRuby and Rubinius equivalent. The specific Ruby versions we build and test on can be found at TravisCI.

Usage

Configuration

EasyGeoIP supports a few free IP geolocation services; the default is Freegeoip but EasyGeoIP can easily be configured to use another service.

# The default geolocation service is Freegeoip
EasyGeoIP.api_service
# => :freegeoip

# Variable assignment
EasyGeoIP.api_service = :nekudo

# Calling `.configure` with Hash argument
EasyGeoIP.configure(api_service: :freegeoip)

# Calling `.configure` with a block
EasyGeoIP.configure do |config|
  config.api_service = :freegeoip
end

Querying IPs - One Method to Rule Them All

Use the query method to retrieve geolocation information for a specified IPv4 or IPv6 address. An instance of EasyGeoIP::GeoData is returned which contains the geolocation information.

EasyGeoIP.query("8.8.8.8")

# => #<EasyGeoIP::GeoData:0x007f91b9512960
 @city="Mountain View",
 @continent_code="NA",
 @country="United States",
 @country_code="US",
 @ip="8.8.8.8",
 @isp="Google Inc.",
 @latitude=37.386,
 @longitude=-122.0838,
 @postal_code="94040",
 @region="California",
 @region_code="CA",
 @time_zone="America/Los_Angeles">

# IPv6 is also supported
EasyGeoIP.query("2001:4860:4860::8888")

Bonus - Pass in nil, an empty string, or no arguments to the .query method and the default geolocation service, Freegeoip will return the geolocation information for your IP address!

EasyGeoIP.query(nil)
EasyGeoIP.query("")
EasyGeoIP.query

EasyGeoIP::GeoData

Regardless of which service you use, geolocation information is returned as a EasyGeoIP::GeoData object where its attributes are easily accessible. Calling #to_hash returns all information as a Hash.

geo_data = EasyGeoIP.query("8.8.8.8")

geo_data.city           # => "Mountain View"
geo_data.continent_code # => "NA"
geo_data.country        # => "United States"
geo_data.country_code   # => "US"
geo_data.ip             # => "8.8.8.8"
geo_data.isp            # => "Google Inc."
geo_data.latitude       # => 37.386
geo_data.longitude      # => -122.0838
geo_data.postal_code    # => "94040"
geo_data.region         # => "California"
geo_data.region_code    # => "CA"
geo_data.time_zone      # => "America/Los_Angeles"

# Return a Hash of all attributes
geo_data.to_hash

{:ip=>"8.8.8.8",
 :country=>"United States",
 :country_code=>"US",
 :city=>"Mountain View",
 :region=>"California",
 :region_code=>"CA",
 :postal_code=>"94040",
 :continent_code=>"NA",
 :latitude=>37.386,
 :longitude=>-122.0838,
 :time_zone=>"America/Los_Angeles",
 :isp=>"Google Inc."}

Errors

In addition to the usual Ruby errors and exceptions, EasyGeoIP can raise the following errors:

• EasyGeoIP::Error::ClientError
• EasyGeoIP::Error::ConnectionFailed
• EasyGeoIP::Error::TimeoutError
• EasyGeoIP::Error::ResourceNotFound
• EasyGeoIP::Error::ParsingError

All of the above error classes inherit EasyGeoIP::Error::ClientError, EasyGeoIP::Error, and StandardError.

Contributing & Development

Please view CONTRIBUTING.md for contributing and development information.

License

EasyGeoIP is Copyright (c) 2015 Gordon Chan and is released under the MIT License. It is free software, and may be redistributed under the terms specified in the LICENSE file.