

Codewake Gem Version Build Status Dependency Status Code Climate


gem install countries

Or you can install via Bundler if you are using Rails. Add this line to your application's Gemfile:

gem 'countries'

And then execute:

$ bundle

Basic Usage


c ='US')


Country Helper

Some apps might not want to constantly call ISO3166::Country this gem has a helper that can provide a Country class

# With global Country Helper
c = Country['US']

This will conflict with any existing Country constant

To Use

gem 'countries', require: 'countries/global'
Upgrading Country Helper to > 1.2.0
gem 'countries', require: 'global'

has become

gem 'countries', require: 'countries/global'

Selective Loading of Locales

As of 2.0 you can selectively load locales to reduce memory usage in production.

By default we load I18n.available_locales if I18n is present, otherwise only [:en]. This means almost any rails environment will only bring in it's supported translations.

You can add all the locales like this.

ISO3166.configure do |config|
  config.locales = [:af, :am, :ar, :as, :az, :be, :bg, :bn, :br, :bs, :ca, :cs, :cy, :da, :de, :dz, :el, :en, :eo, :es, :et, :eu, :fa, :fi, :fo, :fr, :ga, :gl, :gu, :he, :hi, :hr, :hu, :hy, :ia, :id, :is, :it, :ja, :ka, :kk, :km, :kn, :ko, :ku, :lt, :lv, :mi, :mk, :ml, :mn, :mr, :ms, :mt, :nb, :ne, :nl, :nn, :oc, :or, :pa, :pl, :ps, :pt, :ro, :ru, :rw, :si, :sk, :sl, :so, :sq, :sr, :sv, :sw, :ta, :te, :th, :ti, :tk, :tl, :tr, :tt, :ug, :uk, :ve, :vi, :wa, :wo, :xh, :zh, :zu]

or something a bit more simple

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

Attribute-Based Finder Methods


c    = ISO3166::Country.find_country_by_name('united states')
list = ISO3166::Country.find_all_countries_by_region('Americas')
c    = ISO3166::Country.find_country_by_alpha3('can')

For a list of available attributes please see ISO3166::DEFAULT_COUNTRY_HASH. Note: searches are case insensitive and ignore accents.

Country Info

Identification Codes

c.number # => "840"
c.alpha2 # => "US"
c.alpha3 # => "USA"
c.gec    # => "US"

Names & Translations # => "United States"

# Get the names for a country translated to its local languages
c = Country[:BE]
c.local_names # => ["België", "Belgique", "Belgien"]
c.local_name # => "België"

# Get a specific translation

ISO3166::Country.translations         # {"DE"=>"Germany",...}
ISO3166::Country.translations('DE')   # {"DE"=>"Deutschland",...}
ISO3166::Country.all_translated       # ['Germany', ...]
ISO3166::Country.all_translated('DE') # ['Deutschland', ...]

Subdivisions & States

c.subdivisions # => {"CO" => {"name" => "Colorado", "names" => "Colorado"}, ... }


c.latitude # => "38 00 N"
c.longitude # => "97 00 W"
c.latitude_dec # => 39.44325637817383
c.longitude_dec # => -98.95733642578125

c.region # => "Americas"
c.subregion # => "Northern America"

Timezones (optional)

Add tzinfo to your Gemfile and ensure it's required, Countries will not do this for you.

gem 'tzinfo', '~> 1.2', '>= 1.2.2'
c.timezones.zone_identifiers # => ["America/New_York", "America/Detroit", "America/Kentucky/Louisville", ...]
c.timezones.zone_info  # see [tzinfo docs](
c.timezones # see [tzinfo docs](

Telephone Routing (E164)

c.country_code # => "1"
c.national_destination_code_lengths # => 3
c.national_number_lengths # => 10
c.international_prefix # => "011"
c.national_prefix # => "1"

Boundary Boxes

c.min_longitude # => '45'
c.min_latitude # => '22.166667'
c.max_longitude # => '58'
c.max_latitude # => '26.133333'

European Union Membership

c.in_eu? # => false


WARNING if you have a top level class named Money you will conflict with this gem. If this is a large issue we will add a feature to turn currency features off.

Countries now uses the Money gem. What this means is you now get back a Money::Currency object that gives you access to all the currency information.

c.currency.code # => 'USD' # => 'Dollars'
c.currency.symbol # => '$'

Address Formatting



Loading Custom Data

As of 2.0 countries supports loading custom countries / overriding data in it's data set, though if you choose to do this please contribute back to the upstream repo!

Any country registered this way will have it's data available for searching etc... If you are overriding an existing country, for cultural reasons, our code uses a simple merge, not a deep merge so you will need to bring in all data you wish to be available. Bringing in an existing country will also remove it from the internal management of translations, all registered countries will remain in memory.

  alpha2: "LOL",
  name: 'Happy Country',
  translations: {
    'en' => "Happy Country",
    'de' => "glückliches Land"
)'LOL').name == 'Happy Country'



Use native country fields in your model:

field :country, type: Country



# By alpha2

# By object


# By alpha2

# By object


def country

Country Code in Emoji

c = Country['MY']
c.emoji_flag # => "🇺🇸"

Note on Patches/Pull Requests

Please do not submit pull requests on cache/**/*

Any additions should be directed upstream to pkg-isocodes

New Bugs can be filed upstream here If you need to correct an upstream translation please add it to the lib/countries/data/translations_corrections.yaml

# Ex:
# locale:
#   alpha2: localized_name

Any corrections can be applied in translations_corrections.yaml these will be injected during the next rake update_cache

  • Fork the project.
  • Make your feature addition or bug fix.

Copyright (c) 2016 hexorx. See LICENSE for details.