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