countries Ruby Gem

In versions 4.2 and later, the #name attribute was deprecated in favor of #iso_short_name and #iso_long_name to clarify that these follow ISO3166 standards.

If you need the 'common name' (e.g., 'United Kingdom' instead of 'United Kingdom of Great Britain and Northern Ireland'), use the #common_name method, which is a shortcut for #translation('en').

Note: The #name and #names attributes and their corresponding finder methods were completely removed in version 5.0.

To access currency information, you must enable the currency extension in the initializer and add the money gem to your Gemfile.

# 1. Add to Gemfile
gem "money", "~> 6.9"

# 2. Enable in initializer
ISO3166.configuration.enable_currency_extension!

# 3. Usage
c = ISO3166::Country['us']
c.currency.iso_code # => 'USD'
c.currency.name    # => 'United States Dollar'
c.currency.symbol # => '$'

If Mongoid is defined in your project, countries automatically enables Mongoid support. You can use the Country type directly in your Mongoid models to enable native support for searching and saving by either a country object or an alpha2 code.

Note that the database only stores the alpha2 code. The full Country object is rebuilt when the record is queried.

field :country, type: Country

To reduce memory usage in production, you can configure which locales are loaded. By default, it uses I18n.available_locales if I18n is present. If you change the locales after initialization, you must call ISO3166::Data.reset to refresh the cache.

ISO3166.configure do |config|
  config.locales = [:en, :de, :fr, :es]
end

# If changing after initialization:
ISO3166::Data.reset

To retrieve full Money::Currency objects instead of just currency codes, you must enable the currency extension in the ISO3166 configuration. This requires the money gem to be present in your environment.

Use ISO3166::Configuration#enable_currency_extension! to activate this feature.

Since Mongoid stores only the alpha2 code, querying a record returns a Country object. If you want your model to return the country's name (e.g., iso_short_name) by default when accessing the field, override the reader method in your model.

def country
  super.iso_short_name
end

When using field :country, type: Country in a Mongoid model, you can perform queries and assignments using both alpha2 strings and Country objects.

# Searching
# By alpha2
spanish_things = Things.where(country: 'ES')
spanish_things.first.country.iso_short_name    # => "Spain"

# By object
spanish_things = Things.where(country: Country.find_by_iso_short_name('Spain')[1])
spanish_things.first.country.iso_short_name    # => "Spain"

# Saving
# By alpha2
spanish_things = Thing.new(country: 'ES')
spanish_things.save!
spanish_things.country.iso_short_name    # => "Spain"

# By object
spanish_things = Thing.new(country: Country.find_by_iso_short_name('Spain')[1])
spanish_things.save!
spanish_things.country.iso_short_name    # => "Spain"

Retrieve geographic information including coordinates, regions, and bounding boxes.

c = ISO3166::Country.new('US')

# Coordinates
c.latitude  # => "37.09024"
c.longitude # => "-95.712891"

# Regional info
c.world_region # => "AMER"
c.region       # => "Americas"
c.subregion    # => "Northern America"

# Bounding box
c.bounds # => {"northeast"=>{"lat"=>22.166667, "lng"=>58}, "southwest"=>{"lat"=>22.166667, "lng"=>45}}