geo_states 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a0c6519178af969c2358e5ba7402bdec603bf7cd7dc69dd1afc4b43b4b20d48
-  data.tar.gz: 0676e02cd3f7d22b384b6a02b4175122e05029ca04b6e7262c085e4da123611e
+  metadata.gz: 1b757132bddec9472e730189fa998a1ef255440bb12eec76f407c9242b07b685
+  data.tar.gz: 0b5f64fde99b17656d2ced4965c5f766dbcc9b9f533d7ee14389ce83e0c93baa
 SHA512:
-  metadata.gz: 3096bf0c3448fd39ad6044d1ef6fc2f75b588b941c43eee34621344480a2770cf2f9ac0a1ef62f6100b396349b838a3da93888d6232e711c8603a3910d537e69
-  data.tar.gz: dfefb60825e0befbf7414998d982526eff206f22a5dbf1638bbda03252d711f5b76f8e3caee8d612a5db4408444bc8517003d7fc3c2e7c58377032fb24e95f1f
+  metadata.gz: 29f3e3ccc65d2b2f7b5c03f2ec807e754dc4f3c3a4d79b940a2bb91dd32b485e7d5da378a62d511c7e3999cb14babdc661f0b310c7c053870dc4e49a81d897fc
+  data.tar.gz: b06009b62f7580a61cbaba751652c820963046b116d334c0208e45eec37316e45d031c8974caeffd6bb1051f88ed7f0ac28e2cb3bd25c03421526739099c3196

data/README.md

@@ -25,9 +25,9 @@ require "geo_states"
 GeoStates.all_countries
 # => [{:country=>"Mexico", :iso2=>"MX", :iso3=>"MEX", :states=>[...]}, ...]
 
-# Find country by ISO 3166-1 alpha-2 code
+# Find country by any identifier (ISO2, ISO3, M49, or name)
 GeoStates.find_country("MX")
-# => {:country=>"Mexico", :m49=>nil, :iso3=>"MEX", :iso2=>"MX", :currency=>"MXN", ...}
+# => {:country=>"Mexico", :m49=>"484", :iso3=>"MEX", :iso2=>"MX", :currency=>"MXN", ...}
 
 # Find by ISO3, M49, or name
 GeoStates.find_country_by_iso3("MEX")
@@ -37,6 +37,14 @@ GeoStates.find_country_by_name("Mexico")
 # Get states for a country (by iso2, iso3, m49, or name)
 GeoStates.states_for("MX")
 # => [{:name=>"Aguascalientes", :state_code=>"AGU", :iso3=>"AGU", :iso2=>"AG"}, ...]
+
+# Find a specific state
+GeoStates.find_state("MX", "CMX")
+# => {:name=>"Mexico City", :state_code=>"CMX", :iso3=>"CMX", :iso2=>"CM"}
+
+# With user config: CDMX, DF, etc. resolve to Mexico City (see User config below)
+GeoStates.find_state("MX", "CDMX")
+# => {:name=>"Mexico City", :state_code=>"CMX", ...}
 ```
 
 ### Country format
@@ -57,6 +65,60 @@ Each state has:
 - `:iso3` — same as state_code if not provided
 - `:iso2` — derived from state_code if not provided
 
+### Example: what the data looks like
+
+**Country** (e.g. `GeoStates.find_country("MX")`):
+
+```ruby
+{
+  country: "Mexico",
+  m49: "484",
+  iso3: "MEX",
+  iso2: "MX",
+  currency: "MXN",
+  currency_symbol: "$",
+  phone_code: "+52",
+  flag: "https://upload.wikimedia.org/wikipedia/commons/f/fc/Flag_of_Mexico.svg",
+  states: [
+    { name: "Aguascalientes", state_code: "AGU", iso3: "AGU", iso2: "AG" },
+    { name: "Baja California", state_code: "BCN", iso3: "BCN", iso2: "BC" },
+    # ... 30 more states
+  ]
+}
+```
+
+**States** (e.g. `GeoStates.states_for("MX")` — first two):
+
+```ruby
+[
+  { name: "Aguascalientes", state_code: "AGU", iso3: "AGU", iso2: "AG" },
+  { name: "Baja California", state_code: "BCN", iso3: "BCN", iso2: "BC" }
+]
+```
+
+### User config for state aliases
+
+You can add a YAML file to define aliases (e.g. CDMX, DF for Mexico City):
+
+1. Create `config/geo_states.yml` or `geo_states.yml` in your project root
+2. Or set `GEO_STATES_CONFIG_PATH` to the config file path
+
+Example `config/geo_states.yml`:
+
+```yaml
+MX:
+  state_aliases:
+    CDMX: DF
+    DF: DF
+    DISTRITO FEDERAL: DF
+    CIUDAD DE MEXICO: DF
+    MEXICO CITY: DF
+```
+
+Values map to the `state_code` in the bundled data. For Mexico City the data uses `CMX`; `DF` is a built-in alias that maps to `CMX`. So `CDMX` → `DF` → `CMX` works when you have the config.
+
+See `config/geo_states.example.yml` for a copy-paste template.
+
 ## Data sources
 
 The bundled data in `lib/geo_states/data/countries.json` is the single source. It includes:

data/Rakefile

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-Dir.glob("lib/tasks/**/*.rake").each { |r| load r }
+Dir.glob('lib/tasks/**/*.rake').each { |r| load r }
 
 task default: :spec

data/config/geo_states.example.yml

@@ -0,0 +1,14 @@
+# GeoStates: user config for state aliases
+# Copy to config/geo_states.yml or geo_states.yml in your project root.
+# Or set GEO_STATES_CONFIG_PATH to the config file path.
+#
+# Values must map to state_code in bundled data (e.g. CMX for Mexico City).
+# DF is supported as built-in alias for Mexico City (CMX).
+
+MX:
+  state_aliases:
+    CDMX: DF
+    DF: DF
+    DISTRITO FEDERAL: DF
+    CIUDAD DE MEXICO: DF
+    MEXICO CITY: DF

data/lib/geo_states/config_loader.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module GeoStates
+  # Loads user-provided YAML config for state aliases (e.g. CDMX => CMX for Mexico).
+  module ConfigLoader
+    CONFIG_FILENAMES = %w[geo_states.yml geo_states.yaml].freeze
+
+    class << self
+      # @return [Hash] country_iso2 => { alias => state_code }
+      def state_aliases
+        @state_aliases ||= load_state_aliases
+      end
+
+      # Reset cached config (useful for tests).
+      def reset!
+        @state_aliases = nil
+        @config_path = nil
+      end
+
+      # @param path [String] Explicit config file path
+      def config_path=(path)
+        @config_path = path
+        @state_aliases = nil
+      end
+
+      # Resolve state identifier via user config. Returns canonical state_code or nil.
+      # @param country_iso2 [String] e.g. "MX"
+      # @param state_id [String] e.g. "CDMX", "DF"
+      # @return [String, nil] resolved state_code (e.g. "CMX") or nil
+      def resolve_alias(country_iso2, state_id)
+        return nil if country_iso2.nil? || state_id.nil?
+
+        iso2 = country_iso2.to_s.upcase
+        id = state_id.to_s.strip
+
+        aliases = state_aliases[iso2]
+        return nil unless aliases.is_a?(Hash)
+
+        # Support both flat and nested structure:
+        # MX: { CDMX: CMX } or MX: { state_aliases: { CDMX: CMX } }
+        map = aliases['state_aliases'] || aliases
+        return nil unless map.is_a?(Hash)
+
+        val = map[id] || map[id.upcase]
+        val.to_s if val
+      end
+
+      private
+
+      def load_state_aliases
+        path = locate_config
+        return {} unless path && File.file?(path)
+
+        raw = YAML.load_file(path)
+        return {} unless raw.is_a?(Hash)
+
+        raw.transform_keys { |k| k.to_s.upcase }
+      end
+
+      def locate_config
+        return @config_path if defined?(@config_path) && @config_path
+
+        if ENV['GEO_STATES_CONFIG_PATH']
+          p = ENV['GEO_STATES_CONFIG_PATH'].strip
+          return p if !p.empty? && File.file?(p)
+        end
+
+        search_paths.each do |dir|
+          CONFIG_FILENAMES.each do |name|
+            path = File.join(dir, name)
+            return path if File.file?(path)
+          end
+        end
+
+        nil
+      end
+
+      def search_paths
+        paths = []
+        paths << Dir.pwd
+        paths << File.join(Dir.pwd, 'config') if Dir.pwd
+        paths.uniq
+      end
+    end
+  end
+end

data/lib/geo_states/data_loader.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
-require "json"
+require 'json'
 
 module GeoStates
   # Loads country/state data from bundled JSON (no external API at runtime).
   module DataLoader
-    DATA_DIR = File.expand_path("data", __dir__)
-    COUNTRIES_FILE = File.join(DATA_DIR, "countries.json")
+    DATA_DIR = File.expand_path('data', __dir__)
+    COUNTRIES_FILE = File.join(DATA_DIR, 'countries.json')
 
     class << self
       def load_countries
@@ -35,35 +35,36 @@ module GeoStates
       def find_by_m49(m49)
         code = m49.to_s.strip
         return nil if code.empty?
-        code = code.rjust(3, "0") if code.length < 3
+
+        code = code.rjust(3, '0') if code.length < 3
         countries.find { |c| c[:m49].to_s == code }
       end
 
       private
 
       def normalize_country(raw)
-        states = (raw["states"] || []).map { |s| normalize_state(s) }
+        states = (raw['states'] || []).map { |s| normalize_state(s) }
         {
-          country: raw["name"],
-          m49: raw["m49"],
-          iso3: raw["iso3"],
-          iso2: raw["iso2"],
-          currency: raw["currency"],
-          currency_symbol: raw["currency_symbol"],
-          phone_code: raw["phone_code"],
-          flag: raw["flag"],
+          country: raw['name'],
+          m49: raw['m49'],
+          iso3: raw['iso3'],
+          iso2: raw['iso2'],
+          currency: raw['currency'],
+          currency_symbol: raw['currency_symbol'],
+          phone_code: raw['phone_code'],
+          flag: raw['flag'],
           states: states
         }
       end
 
       def normalize_state(raw)
-        code = raw["state_code"].to_s
+        code = raw['state_code'].to_s
         iso2 = code.length >= 2 ? code[0, 2].upcase : code.upcase
         {
-          name: raw["name"],
+          name: raw['name'],
           state_code: code,
-          iso3: raw["iso3"] || code,
-          iso2: raw["iso2"] || iso2
+          iso3: raw['iso3'] || code,
+          iso2: raw['iso2'] || iso2
         }
       end
     end

data/lib/geo_states/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GeoStates
-  VERSION = "0.1.1"
+  VERSION = '0.1.3'
 end

data/lib/geo_states.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
-require_relative "geo_states/version"
-require "geo_states/data_loader"
+require_relative 'geo_states/version'
+require_relative 'geo_states/config_loader'
+require 'geo_states/data_loader'
 
 module GeoStates
   class Error < StandardError; end
@@ -12,20 +13,37 @@ module GeoStates
     DataLoader.countries
   end
 
-  # Find country by ISO 3166-1 alpha-2 (e.g. "MX", "US").
+  # Find country by any identifier (ISO2, ISO3, M49, or name).
+  # @param identifier [String] e.g. "MX", "MEX", "484", "Mexico"
+  # @return [Hash, nil]
+  def self.find_country(identifier)
+    find_country_by_iso2(identifier) ||
+      find_country_by_iso3(identifier) ||
+      find_country_by_m49(identifier) ||
+      find_country_by_name(identifier)
+  end
+
+  # Find country by ISO 3166-1 alpha-2 code (e.g. "MX", "US").
   # @param iso2 [String]
   # @return [Hash, nil]
-  def self.find_country(iso2)
+  def self.find_country_by_iso2(iso2)
     DataLoader.find_by_iso2(iso2)
   end
 
-  # Find country by ISO 3166-1 alpha-3 (e.g. "MEX", "USA").
+  # Find country by ISO 3166-1 alpha-3 code (e.g. "MEX", "USA").
   # @param iso3 [String]
   # @return [Hash, nil]
   def self.find_country_by_iso3(iso3)
     DataLoader.find_by_iso3(iso3)
   end
 
+  # Find country by UN M49 numeric code (e.g. "484", 484).
+  # @param m49 [String, Integer]
+  # @return [Hash, nil]
+  def self.find_country_by_m49(m49)
+    DataLoader.find_by_m49(m49)
+  end
+
   # Find country by name (case-insensitive).
   # @param name [String]
   # @return [Hash, nil]
@@ -33,13 +51,45 @@ module GeoStates
     DataLoader.find_by_name(name)
   end
 
-  # States for a country (by iso2, iso3, or country name).
-  # @param identifier [String] ISO2, ISO3, or country name
+  # Return states (subdivisions) for a country. Accepts ISO2, ISO3, M49, or name.
+  # @param identifier [String] ISO2, ISO3, M49, or country name
   # @return [Array<Hash>]
   def self.states_for(identifier)
-    country = find_country(identifier) ||
-              find_country_by_iso3(identifier) ||
-              find_country_by_name(identifier)
+    country = find_country(identifier)
     country&.dig(:states) || []
   end
+
+  # Find a state within a country. Accepts user YAML config for aliases (e.g. CDMX => CMX).
+  # Config file: config/geo_states.yml or geo_states.yml, or GEO_STATES_CONFIG_PATH env.
+  # @param country_id [String] ISO2, ISO3, M49, or country name (e.g. "MX", "Mexico")
+  # @param state_id [String] state_code, name, or alias from user config (e.g. "CMX", "CDMX", "Mexico City")
+  # @return [Hash, nil] state hash with :name, :state_code, :iso2, :iso3, or nil
+  def self.find_state(country_id, state_id)
+    country = find_country(country_id)
+    return nil unless country
+
+    canonical = resolve_state_id(country[:iso2], state_id.to_s)
+    return nil if canonical.nil? || canonical.empty?
+
+    states = country[:states] || []
+    states.find do |s|
+      s[:state_code].to_s.casecmp(canonical) == 0 ||
+        s[:name].to_s.casecmp(canonical) == 0
+    end
+  end
+
+  # Resolve state identifier: user config first, then built-in aliases (e.g. DF -> CMX for Mexico).
+  # @param iso2 [String] country ISO2
+  # @param state_id [String] user input
+  # @return [String] canonical state_code for lookup
+  def self.resolve_state_id(iso2, state_id)
+    id = state_id.to_s.strip
+    return nil if id.empty?
+
+    canonical = ConfigLoader.resolve_alias(iso2, id) || id
+    # Built-in: Mexico DF -> CMX (bundled data uses CMX; user config may map CDMX => DF)
+    return 'CMX' if iso2.to_s.upcase == 'MX' && canonical.to_s.upcase == 'DF'
+
+    canonical
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: geo_states
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Alberto Osnaya (@elosnaya)
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-17 00:00:00.000000000 Z
+date: 2026-02-20 00:00:00.000000000 Z
 dependencies: []
 description: Lists countries and their states (or provinces, regions) in a consistent
   format. Data is bundled with the gem.
@@ -21,9 +21,11 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- config/geo_states.example.yml
 - geo_states-0.1.0.gem
 - geo_states/data/countries.json
 - lib/geo_states.rb
+- lib/geo_states/config_loader.rb
 - lib/geo_states/data/countries.json
 - lib/geo_states/data_loader.rb
 - lib/geo_states/version.rb