{"id":22306555,"url":"https://github.com/rameerez/trackdown","last_synced_at":"2026-01-02T02:57:17.791Z","repository":{"id":260005530,"uuid":"864132010","full_name":"rameerez/trackdown","owner":"rameerez","description":"📍 Ruby gem to geolocate IPs (MaxMind BYOK)","archived":false,"fork":false,"pushed_at":"2024-10-30T15:25:41.000Z","size":40,"stargazers_count":19,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-15T04:10:02.690Z","etag":null,"topics":["geoip","geolocation","ip","ip-address","ipv4","ipv6","maxmind","maxmind-db","maxmind-geoip","rails","ruby","ruby-gem","ruby-on-rails","user-tracking"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rameerez.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-27T14:52:08.000Z","updated_at":"2025-01-08T11:13:44.000Z","dependencies_parsed_at":null,"dependency_job_id":"fb89b96e-cdea-4465-9f52-17fc9e28688f","html_url":"https://github.com/rameerez/trackdown","commit_stats":null,"previous_names":["rameerez/trackdown"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rameerez%2Ftrackdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rameerez%2Ftrackdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rameerez%2Ftrackdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rameerez%2Ftrackdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rameerez","download_url":"https://codeload.github.com/rameerez/trackdown/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234715616,"owners_count":18875905,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["geoip","geolocation","ip","ip-address","ipv4","ipv6","maxmind","maxmind-db","maxmind-geoip","rails","ruby","ruby-gem","ruby-on-rails","user-tracking"],"created_at":"2024-12-03T19:29:19.474Z","updated_at":"2026-01-02T02:57:17.785Z","avatar_url":"https://github.com/rameerez.png","language":"Ruby","readme":"# 📍 `trackdown` - Ruby gem to geolocate IPs\n\n`trackdown` is a Ruby gem that allows you to geolocate IP addresses easily. It works out-of-the-box with **Cloudflare** (zero config!); and it's also a simple, convenient wrapper on top of **MaxMind** (just bring your own MaxMind key, and you're good to go!). `trackdown` offers a clean API for Rails applications to fetch country, city, and emoji flag information for any IP address.\n\nGiven an IP, it gives you the corresponding:\n- 🗺️ Country (two-letter country code + country name)\n- 📍 City\n- 🇺🇸 Emoji flag of the country\n\n## Two ways to use `trackdown`\n\n### Option 1: Cloudflare (recommended, zero config)\n\nIf your app is behind Cloudflare, you can use `trackdown` with **zero configuration**:\n- No API keys needed\n- No database downloads\n- No external dependencies\n- Instant lookups from Cloudflare headers\n\nJust enable \"IP Geolocation\" in your Cloudflare dashboard and you're done! We automatically check for the Cloudflare headers in the context of a `request` and provide you with the IP geo data.\n\n### Option 2: MaxMind (BYOK - Bring Your Own Key)\n\nFor apps not behind Cloudflare, offline apps, non-Rails apps, or as a fallback, use MaxMind:\n- Requires MaxMind account and license key\n- Requires downloading and maintaining a local database\n- Works offline once database is downloaded\n- Get started at [MaxMind](https://www.maxmind.com/)\n\n### Option 3: Auto\n\nBy default, `trackdown` uses **`:auto` mode** which tries Cloudflare first and falls back to MaxMind automatically.\n\n\u003e [!NOTE]\n\u003e Trackdown fails gracefully. If no provider is available (no Cloudflare headers, no MaxMind database), it returns `'Unknown'` instead of raising an error, so your app doesn't crash due to a missing geolocation provider.\n\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'trackdown'\n\n# Optional: Only needed if using MaxMind provider\ngem 'maxmind-db'        # For MaxMind database access\ngem 'connection_pool'   # For connection pooling\n```\n\nAnd then execute:\n\n```bash\nbundle install\n```\n\n## Setup\n\n### Quick Start (Cloudflare)\n\nIf your app is behind Cloudflare, setup is super simple:\n\n1. **Enable IP Geolocation in Cloudflare**\n\n2. **That's it!** No initializer needed. Just use it:\n\n```ruby\n# In your controller\nTrackdown.locate(request.remote_ip, request: request).country\n# =\u003e 'United States'\n```\n\n### Setup with MaxMind\n\nIf you want to use `trackdown` with a MaxMind database as the geo IP data provider:\n\n1. **Run the generator**:\n```bash\nrails generate trackdown:install\n```\n\nThis will create an initializer file at `config/initializers/trackdown.rb`. Open this file and add your MaxMind license key and account ID next.\n\n2. **Configure your MaxMind credentials** in `config/initializers/trackdown.rb`:\n```ruby\nTrackdown.configure do |config|\n  config.provider = :auto  # or :maxmind to use MaxMind exclusively\n\n  # Use Rails credentials (recommended)\n  config.maxmind_account_id = Rails.application.credentials.dig(:maxmind, :account_id)\n  config.maxmind_license_key = Rails.application.credentials.dig(:maxmind, :license_key)\nend\n```\n\n\u003e [!TIP]\n\u003e To get your MaxMind account ID and license key, you need to create an account at [MaxMind](https://www.maxmind.com/) and get a license key.\n\n3. **Download the database**:\n```ruby\nTrackdown.update_database\n```\n\nYou can configure the path where the MaxMind database will be stored. By default, it will be stored at `db/GeoLite2-City.mmdb`:\n\n```ruby\nconfig.database_path = Rails.root.join('db', 'GeoLite2-City.mmdb').to_s\n```\n\n4. **Schedule regular updates** (optional but recommended):\n\nThe `trackdown` gem generator 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.\n\nTo 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.\n\n\nIf 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:\n\n```yaml\nproduction:\n  refresh_trackdown_database:\n    class: TrackdownDatabaseRefreshJob\n    queue: default\n    schedule: every Saturday at 4am US/Pacific\n```\n\n\u003e [!NOTE]\n\u003e MaxMind updates their databases [every Tuesday and Friday](https://dev.maxmind.com/geoip/geoip2/geoip2-update-process/).\n\n## Usage\n\n### With Cloudflare (recommended when available)\n\n```ruby\n# In your controller - pass the request object\nresult = Trackdown.locate(request.remote_ip, request: request)\nresult.country\n# =\u003e 'United States'\n```\n\n### With MaxMind or without request object\n\nTo geolocate an IP address:\n\n```ruby\n# Works anywhere - just needs the IP\nresult = Trackdown.locate('8.8.8.8')\nresult.country\n# =\u003e 'United States'\n```\n\n### API Methods\n\nYou can do things like:\n```ruby\nTrackdown.locate('8.8.8.8').emoji\n# =\u003e '🇺🇸'\n```\n\nIn fact, there are a few methods you can use:\n\n```ruby\nresult.country_code    # =\u003e 'US'\nresult.country_name    # =\u003e 'United States'\nresult.country         # =\u003e 'United States' (alias for country_name)\nresult.city            # =\u003e 'Mountain View' (from MaxMind or Cloudflare's \"Add visitor location headers\")\nresult.flag_emoji      # =\u003e '🇺🇸'\nresult.emoji           # =\u003e '🇺🇸' (alias for flag_emoji)\nresult.country_flag    # =\u003e '🇺🇸' (alias for flag_emoji)\nresult.country_info    # =\u003e # Rich country data from the `countries` gem\n```\n\n### Rich country information\n\nFor `country_info` we're leveraging the [`countries`](https://github.com/countries/countries) gem, so you get a lot of information about the country, like the continent, the region, the languages spoken, the currency, and more:\n\n```ruby\nresult.country_info.alpha3          # =\u003e \"USA\"\nresult.country_info.currency_code   # =\u003e \"USD\"\nresult.country_info.continent       # =\u003e 'North America'\nresult.country_info.nationality     # =\u003e 'American'\nresult.country_info.iso_long_name   # =\u003e 'The United States of America'\n```\n\n### Hash data\n\nIf you prefer, you can also get all the information as a hash:\n\n```ruby\nresult.to_h\n# =\u003e {\n#      country_code: 'US',\n#      country_name: 'United States',\n#      city: 'Mountain View',\n#      flag_emoji: '🇺🇸',\n#      country_info: { ... }\n#    }\n```\n\n## Configuration\n\n### Provider Options\n\n```ruby\nTrackdown.configure do |config|\n  # :auto - Try Cloudflare first, fall back to MaxMind (default, recommended)\n  # :cloudflare - Only use Cloudflare headers\n  # :maxmind - Only use MaxMind database\n  config.provider = :auto\nend\n```\n\n### Full Configuration Example\n\n```ruby\nTrackdown.configure do |config|\n  # Provider\n  config.provider = :auto\n\n  # MaxMind settings (only needed if using MaxMind)\n  config.maxmind_account_id = Rails.application.credentials.dig(:maxmind, :account_id)\n  config.maxmind_license_key = Rails.application.credentials.dig(:maxmind, :license_key)\n  config.database_path = Rails.root.join('db', 'GeoLite2-City.mmdb').to_s\n\n  # Performance tuning (MaxMind only - requires maxmind-db gem)\n  config.timeout = 3\n  config.pool_size = 5\n  config.pool_timeout = 3\n  # config.memory_mode = MaxMind::DB::MODE_MEMORY  # or MODE_FILE to reduce memory\n\n  # General\n  config.reject_private_ips = true  # Reject 192.168.x.x, 127.0.0.1, etc.\nend\n```\n\n### Updating the MaxMind database\n\nOnly needed when using the MaxMind provider:\n\n```ruby\nTrackdown.update_database\n```\n\n## How It Works\n\n### Cloudflare Provider\n\nWhen you enable \"IP Geolocation\" in Cloudflare, they add the `CF-IPCountry` header to every request. If you enable \"Add visitor location headers\" (via Managed Transforms), you also get `CF-IPCity`.\n\nTrackdown reads these headers directly from the request with zero overhead, and no database lookups.\n\n### MaxMind Provider\n\nDownloads the GeoLite2-City database to your server and performs local lookups using connection pooling for performance.\n\n\n## Development\n\nAfter checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec rake test` to run the Minitest tests.\n\nTo install this gem onto your local machine, run `bundle exec rake install`.\n\n## Contributing\n\nBug 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.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","funding_links":[],"categories":["Ruby"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frameerez%2Ftrackdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frameerez%2Ftrackdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frameerez%2Ftrackdown/lists"}