trackdown 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ac258f067b151ee511c897d3460694466ed9ea36e2ff96010cccb5acf106b16
-  data.tar.gz: 1120ed37341b3fe876ed38997440537968e9014a1918b0c2c12acd3d10c36615
+  metadata.gz: 675d77c9715d2b1de76e4d385b95960b82f45355edb57689d2cf243197f19324
+  data.tar.gz: 061e61803019b00dd99e2d186f3c3ccbe73cf5ee9a750b513e1dfc11c46c0859
 SHA512:
-  metadata.gz: fd9029fb452c671613dcadb3081fc8e036634506f564b354997798d4b59617ac316c19976ae0ea2d9f4cfbc6a6d16a9a7729fc70d60d6a47354a808205bb6106
-  data.tar.gz: 94a789bbd321cb389590c466da2de5c7887812c9362d086a3d35446a428bd2a2a6a398f485d7629f86fec24e7e51a5b26d9871e512a4bb4e49f10edf9de45f7b
+  metadata.gz: 5394b49ff9c641ae941675b2bc18da7e92d934effab2f771707ded19179ea4f019a5c18533dc059e5e8f12e7cf6ff0847d0e3dd91586e1e218bb7f0f3d96c139
+  data.tar.gz: bddbc1ea728846d08dd1ca75033c3a9b3eb95144fdbec641089593c8f1e177e3ac52eb9cb495b2a14bbc118d99d23a504f2ecbe37578017629f9344e13faf0d7

data/.simplecov

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+SimpleCov.start do
+  formatter SimpleCov::Formatter::SimpleFormatter
+
+  add_filter "/test/"
+
+  track_files "{lib,app}/**/*.rb"
+
+  enable_coverage :branch
+
+  minimum_coverage line: 80, branch: 65
+
+  command_name "Job #{ENV['TEST_ENV_NUMBER']}" if ENV['TEST_ENV_NUMBER']
+end
+
+SimpleCov.at_exit do
+  SimpleCov.result.format!
+  puts "\n" + "=" * 60
+  puts "COVERAGE SUMMARY"
+  puts "=" * 60
+  puts "Line Coverage:   #{SimpleCov.result.covered_percent.round(2)}%"
+  puts "Branch Coverage: #{SimpleCov.result.coverage_statistics[:branch]&.percent&.round(2) || 'N/A'}%"
+  puts "=" * 60
+end

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## [0.3.0] - 2026-02-08
+
+- Add 8 new geolocation fields: `region`, `region_code`, `continent`, `timezone`, `latitude`, `longitude`, `postal_code`, `metro_code`
+- All new fields available from both Cloudflare and MaxMind providers
+- All 10 Cloudflare "Add visitor location headers" now fully supported
+- Backward compatible — all new fields are optional, existing API unchanged
+- `to_h` now includes all new fields
+
 ## [0.2.0] - 2026-01-02
 
 - Completely decouple Maxmind from the gem, making it optional

data/README.md

@@ -1,23 +1,36 @@
 # 📍 `trackdown` - Ruby gem to geolocate IPs
 
-`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.
+> [!TIP]
+> **🚀 Ship your next Rails app 10x faster!** I've built **[RailsFast](https://railsfast.com/?ref=trackdown)**, a production-ready Rails boilerplate template that comes with everything you need to launch a software business in days, not weeks. Go [check it out](https://railsfast.com/?ref=trackdown)!
+
+`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, region, continent, timezone, coordinates, and emoji flag information for any IP address.
 
 Given an IP, it gives you the corresponding:
 - 🗺️ Country (two-letter country code + country name)
 - 📍 City
+- 🏔️ Region / state (e.g. "California") and region code (e.g. "CA")
+- 🌍 Continent (e.g. "NA", "EU")
+- 🕐 Timezone (e.g. "America/Los_Angeles")
+- 📌 Latitude and longitude coordinates
+- 📮 Postal code (e.g. "94107")
+- 📺 Metro code (e.g. "807")
 - 🇺🇸 Emoji flag of the country
 
-## Two ways to use `trackdown`
+## First, choose your `trackdown` Geo IP provider
 
 ### Option 1: Cloudflare (recommended, zero config)
 
-If your app is behind Cloudflare, you can use `trackdown` with **zero configuration**:
+If your Rails app is behind Cloudflare, you can use `trackdown` with **zero configuration**:
 - No API keys needed
 - No database downloads
 - No external dependencies
 - Instant lookups from Cloudflare headers
 
-Just 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.
+Just enable "IP Geolocation" in your Cloudflare dashboard and you're done! For the full set of location fields (city, region, coordinates, etc.), enable ["Add visitor location headers"](https://developers.cloudflare.com/rules/transform/managed-transforms/reference/) in Managed Transforms. We automatically read these headers from the `request` and provide you with the IP geo data.
 
 ### Option 2: MaxMind (BYOK - Bring Your Own Key)
 
@@ -162,12 +175,23 @@ result.country_code    # => 'US'
 result.country_name    # => 'United States'
 result.country         # => 'United States' (alias for country_name)
 result.city            # => 'Mountain View' (from MaxMind or Cloudflare's "Add visitor location headers")
+result.region          # => 'California'
+result.region_code     # => 'CA'
+result.continent       # => 'NA'
+result.timezone        # => 'America/Los_Angeles'
+result.latitude        # => 37.7749
+result.longitude       # => -122.4194
+result.postal_code     # => '94107'
+result.metro_code      # => '807'
 result.flag_emoji      # => '🇺🇸'
 result.emoji           # => '🇺🇸' (alias for flag_emoji)
 result.country_flag    # => '🇺🇸' (alias for flag_emoji)
 result.country_info    # => # Rich country data from the `countries` gem
 ```
 
+> [!NOTE]
+> The `region`, `region_code`, `continent`, `timezone`, `latitude`, `longitude`, `postal_code`, and `metro_code` fields require Cloudflare's ["Add visitor location headers"](https://developers.cloudflare.com/rules/transform/managed-transforms/reference/) Managed Transform to be enabled, or a MaxMind GeoLite2-City database. These fields return `nil` when not available.
+
 ### Rich country information
 
 For `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:
@@ -191,6 +215,14 @@ result.to_h
 #      country_name: 'United States',
 #      city: 'Mountain View',
 #      flag_emoji: '🇺🇸',
+#      region: 'California',
+#      region_code: 'CA',
+#      continent: 'NA',
+#      timezone: 'America/Los_Angeles',
+#      latitude: 37.7749,
+#      longitude: -122.4194,
+#      postal_code: '94107',
+#      metro_code: '807',
 #      country_info: { ... }
 #    }
 ```
@@ -243,13 +275,26 @@ Trackdown.update_database
 
 ### Cloudflare Provider
 
-When 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`.
+When you enable "IP Geolocation" in Cloudflare, they add the `CF-IPCountry` header to every request. If you also enable ["Add visitor location headers"](https://developers.cloudflare.com/rules/transform/managed-transforms/reference/) (via Managed Transforms), you get all 10 location headers:
+
+| Cloudflare header | `trackdown` field |
+|---|---|
+| `cf-ipcountry` | `country_code` |
+| `cf-ipcity` | `city` |
+| `cf-ipcontinent` | `continent` |
+| `cf-iplatitude` | `latitude` |
+| `cf-iplongitude` | `longitude` |
+| `cf-region` | `region` |
+| `cf-region-code` | `region_code` |
+| `cf-metro-code` | `metro_code` |
+| `cf-postal-code` | `postal_code` |
+| `cf-timezone` | `timezone` |
 
-Trackdown reads these headers directly from the request with zero overhead, and no database lookups.
+Trackdown reads these headers directly from the request with zero overhead — no database lookups, no external API calls.
 
 ### MaxMind Provider
 
-Downloads the GeoLite2-City database to your server and performs local lookups using connection pooling for performance.
+Downloads the [GeoLite2-City](https://dev.maxmind.com/geoip/docs/databases/city-and-country/) database to your server and performs local lookups using connection pooling for performance. All fields (`country`, `city`, `region`, `continent`, `timezone`, `latitude`, `longitude`, `postal_code`, `metro_code`) are extracted from the database record.
 
 
 ## Development

data/Rakefile

@@ -7,7 +7,6 @@ Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"
   t.test_files = FileList["test/**/*_test.rb"]
-  t.verbose = true
 end
 
 task default: :test

data/lib/trackdown/location_result.rb

@@ -4,13 +4,26 @@ require 'countries'
 
 module Trackdown
   class LocationResult
-    attr_reader :country_code, :country_name, :city, :flag_emoji
+    attr_reader :country_code, :country_name, :city, :flag_emoji,
+                :region, :region_code, :continent, :timezone, :latitude, :longitude,
+                :postal_code, :metro_code
 
-    def initialize(country_code, country_name, city, flag_emoji)
+    def initialize(country_code, country_name, city, flag_emoji,
+                   region: nil, region_code: nil, continent: nil,
+                   timezone: nil, latitude: nil, longitude: nil,
+                   postal_code: nil, metro_code: nil)
       @country_code = country_code
       @country_name = country_name
       @city = city
       @flag_emoji = flag_emoji
+      @region = region
+      @region_code = region_code
+      @continent = continent
+      @timezone = timezone
+      @latitude = latitude
+      @longitude = longitude
+      @postal_code = postal_code
+      @metro_code = metro_code
     end
 
     alias_method :country, :country_name
@@ -29,6 +42,14 @@ module Trackdown
         country_name: @country_name,
         city: @city,
         flag_emoji: @flag_emoji,
+        region: @region,
+        region_code: @region_code,
+        continent: @continent,
+        timezone: @timezone,
+        latitude: @latitude,
+        longitude: @longitude,
+        postal_code: @postal_code,
+        metro_code: @metro_code,
         country_info: country_info&.data || {}
       }
     end

data/lib/trackdown/providers/cloudflare_provider.rb

@@ -13,6 +13,14 @@ module Trackdown
     class CloudflareProvider < BaseProvider
       COUNTRY_HEADER = 'HTTP_CF_IPCOUNTRY'
       CITY_HEADER = 'HTTP_CF_IPCITY'
+      REGION_HEADER = 'HTTP_CF_REGION'
+      REGION_CODE_HEADER = 'HTTP_CF_REGION_CODE'
+      LATITUDE_HEADER = 'HTTP_CF_IPLATITUDE'
+      LONGITUDE_HEADER = 'HTTP_CF_IPLONGITUDE'
+      TIMEZONE_HEADER = 'HTTP_CF_TIMEZONE'
+      CONTINENT_HEADER = 'HTTP_CF_IPCONTINENT'
+      METRO_CODE_HEADER = 'HTTP_CF_METRO_CODE'
+      POSTAL_CODE_HEADER = 'HTTP_CF_POSTAL_CODE'
 
       # Special Cloudflare country codes
       UNKNOWN_CODE = 'XX'
@@ -43,7 +51,17 @@ module Trackdown
           city = extract_city(request)
           flag_emoji = get_emoji_flag(country_code)
 
-          LocationResult.new(country_code, country_name, city, flag_emoji)
+          LocationResult.new(
+            country_code, country_name, city, flag_emoji,
+            region: extract_header(request, REGION_HEADER),
+            region_code: extract_header(request, REGION_CODE_HEADER),
+            continent: extract_header(request, CONTINENT_HEADER),
+            timezone: extract_header(request, TIMEZONE_HEADER),
+            latitude: parse_coordinate(request.env[LATITUDE_HEADER]),
+            longitude: parse_coordinate(request.env[LONGITUDE_HEADER]),
+            postal_code: extract_header(request, POSTAL_CODE_HEADER),
+            metro_code: extract_header(request, METRO_CODE_HEADER)
+          )
         end
 
         private
@@ -64,6 +82,21 @@ module Trackdown
 
           city
         end
+
+        def extract_header(request, header)
+          value = request.env[header]
+          return nil if value.nil? || value.empty?
+
+          value
+        end
+
+        def parse_coordinate(value)
+          return nil if value.nil? || value.empty?
+
+          Float(value)
+        rescue ArgumentError, TypeError
+          nil
+        end
       end
     end
   end

data/lib/trackdown/providers/maxmind_provider.rb

@@ -48,7 +48,17 @@ module Trackdown
           city = extract_city(record)
           flag_emoji = get_emoji_flag(country_code)
 
-          LocationResult.new(country_code, country_name, city, flag_emoji)
+          LocationResult.new(
+            country_code, country_name, city, flag_emoji,
+            region: extract_region(record),
+            region_code: record&.dig('subdivisions', 0, 'iso_code'),
+            continent: record&.dig('continent', 'code'),
+            timezone: record&.dig('location', 'time_zone'),
+            latitude: record&.dig('location', 'latitude'),
+            longitude: record&.dig('location', 'longitude'),
+            postal_code: record&.dig('postal', 'code'),
+            metro_code: record&.dig('location', 'metro_code')&.to_s
+          )
         end
 
         private
@@ -103,6 +113,11 @@ module Trackdown
             (record&.dig('city', 'names')&.values&.first) ||
             'Unknown'
         end
+
+        def extract_region(record)
+          record&.dig('subdivisions', 0, 'names', 'en') ||
+            record&.dig('subdivisions', 0, 'names')&.values&.first
+        end
       end
     end
   end

data/lib/trackdown/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Trackdown
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: trackdown
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-01-02 00:00:00.000000000 Z
+date: 2026-02-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: countries
@@ -23,129 +23,19 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '7.0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-- !ruby/object:Gem::Dependency
-  name: rubocop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.21'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.21'
-- !ruby/object:Gem::Dependency
-  name: minitest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.25'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.25'
-- !ruby/object:Gem::Dependency
-  name: mocha
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-- !ruby/object:Gem::Dependency
-  name: simplecov
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.22'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.22'
-- !ruby/object:Gem::Dependency
-  name: webmock
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-- !ruby/object:Gem::Dependency
-  name: maxmind-db
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.2'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.2'
-- !ruby/object:Gem::Dependency
-  name: connection_pool
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.4'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.4'
-description: Trackdown is a Ruby gem that easily allows you to geolocate IP addresses.
-  It works out of the box with Cloudflare headers if you're using it, or you can use
-  MaxMind (BYOK). The gem offers a clean API for Rails applications to fetch country,
-  city, and emoji flag information for any IP address. Supports Cloudflare headers
-  (instant, zero overhead) and MaxMind GeoLite2 database (offline capable).
+description: Trackdown is a Ruby gem that allows you to geolocate IP addresses easily.
+  It works out of the box with Cloudflare headers if your Rails app is behind it;
+  or you can also use MaxMind databases (BYOK). The gem offers a clean API for Rails
+  applications to fetch country, city, emoji flag, region, continent, postal code,
+  latitude, longitude and other GeoIP information for any IP address. Supports Cloudflare
+  headers, and MaxMind GeoLite2 databases (offline capable).
 email:
 - rubygems@rameerez.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".simplecov"
 - AGENTS.md
 - CHANGELOG.md
 - CLAUDE.md
@@ -173,6 +63,7 @@ licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
   homepage_uri: https://github.com/rameerez/trackdown
   source_code_uri: https://github.com/rameerez/trackdown
   changelog_uri: https://github.com/rameerez/trackdown/blob/main/CHANGELOG.md