📍 trackdown - Ruby gem to geolocate IPs (MaxMind BYOK)

trackdown is a Ruby gem that easily allows you to geolocate IP addresses. It’s a simple, convenient wrapper on top of MaxMind. Just bring your own MaxMind keys, and you’re good to go. It keeps your MaxMind database updated regularly, and it offers a handy API for Rails applications to fetch country, city, and emoji flag information for any IP address.

Given an IP, it gives you the corresponding:

• 🗺️ Country (two-letter country code + country name)
• 📍 City
• 🇺🇸 Emoji flag of the country

trackdown is BYOK (Bring Your Own Key) – you’ll need your own MaxMind keys for it to work. It’s your responsibility to make sure your app complies with the license for the MaxMind database you’re using. Get a MaxMind account and license key at MaxMind.

Installation

Add this line to your application’s Gemfile:

gem 'trackdown'

And then execute:

bundle install

Setup

First, run the installation generator:

rails generate trackdown:install

This will create an initializer file at config/initializers/trackdown.rb. Open this file and add your MaxMind license key and account ID:

Trackdown.configure do |config|
  # Tip: do not write your plaintext keys in the code, use Rails.application.credentials instead
  config.maxmind_account_id = 'your_account_id_here'
  config.maxmind_license_key = 'your_license_key_here'
end

[!TIP]
To get your MaxMind account ID and license key, you need to create an account at MaxMind and get a license key.

You can also configure the path where the MaxMind database will be stored. By default, it will be stored at db/GeoLite2-City.mmdb:

config.database_path = Rails.root.join('db', 'GeoLite2-City.mmdb').to_s

The generator also creates a TrackdownDatabaseRefreshJob job for regularly updating the MaxMind database. You can just get a database the first time and just keep using it, but the information will get outdated and some IPs will become stale or inaccurate.

To keep your IP geolocation accurate, you need to make sure the TrackdownDatabaseRefreshJob runs regularly. How you do that, exactly, depends on the queueing system you’re using.

If you’re using solid_queue (the Rails 8 default), you can easily add it to your schedule in the config/recurring.yml file like this:

production:
  refresh_trackdown_database:
    class: TrackdownDatabaseRefreshJob
    queue: default
    schedule: every Saturday at 4am US/Pacific

Note: MaxMind updates their databases every Tuesday and Friday.

After setting everything up, you can run the following command to update the MaxMind database / get the first fresh copy of it:

Trackdown.update_database

Usage

To geolocate an IP address:

Trackdown.locate('8.8.8.8').country
# => 'United States'

You can also do things like:

Trackdown.locate('8.8.8.8').emoji
# => '🇺🇸'

In fact, there are a few methods you can use:

result = Trackdown.locate('8.8.8.8')

result.country_code    # => 'US'
result.country_name    # => 'United States'
result.country         # => 'United States' (alias for country_name)
result.country_info    # => # A big hash of information about the country, from the `countries` gem
result.city            # => 'Mountain View'
result.flag_emoji      # => '🇺🇸'
result.emoji           # => '🇺🇸' (alias for flag_emoji)
result.country_flag    # => '🇺🇸' (alias for flag_emoji)

For country_info we’re leveraging the countries gem, so you get a lot of information about the country, like the continent, the region, the languages spoken, the currency, and more:

result.country_info.alpha3          # => "USA"
result.country_info.currency_code   # => "USD"
result.country_info.continent       # => 'North America'
result.country_info.nationality     # => 'American'
result.country_info.iso_long_name   # => 'The United States of America'

If you prefer, you can also get all the information as a hash:

result.to_h
# => {
#      country_code: 'US',
#      country_name: 'United States',
#      city: 'Mountain View',
#      flag_emoji: '🇺🇸',
#      country_info: { ... }
#    }

To manually update the MaxMind IP database:

Trackdown.update_database

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/rameerez/trackdown. Our code of conduct is: just be nice and make your mom proud of what you do and post online.

License

The gem is available as open source under the terms of the MIT License.