All sorts of useful information about every country packaged as pretty little country objects. It includes data from ISO 3166 (countries and states/subdivisions ), ISO 4217 (currency), and E.164 (phone numbers). As a bonus it even adds a country_select helper to rails projects.
Pull request Compare This branch is 630 commits behind hexorx:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



Countries is a collection of all sorts of useful information for every country in the ISO 3166 standard. It contains info for the following standards ISO3166-1(countries), ISO3166-2(states/subdivisions), ISO4217(currency) and E.164(phone numbers). The gem also adds a country_select helper. I will add any country based data I can get access to. I hope this to be a repository for all country based information.

Build Status Dependency Status Code Climate Issues in Ready


gem install countries

If you’re in Rails 2.3 or earlier, place this in your environment.rb:

config.gem 'countries'

Or you can install via bundler Gemfile if you are using Rails 3:

gem 'countries'

Or you can install via bundler Gemfile with using only ISO3166::Country (no Country class):

gem 'countries', :require => 'iso3166'

Country Select Helper

This gem automatically integrates with country_select. It will change its behavior to store the alpha2 country code instead of the country name. Make sure to add the country_select gem after countries in the Gemfile:

gem 'countries'
gem 'country_select'

Basic Usage

Note that Country class still exist by default. (is inherited from ISO3166::Country to keep backward compatibility).

Simply load a new country object using or the shortcut Country[alpha2]. An example works best.

c ='US')
c = Country['US']

Attribute-Based Finder Methods

You can lookup a country or an array of countries using any of the data attributes via the find_country_by_attribute dynamic methods:

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

For a list of available attributes please see ISO3166::Country::AttrReaders. Note: searches are case insensitive.

Country Info

Identification Codes

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

Names & Translations #=> "United States"
c.names #=> ["United States of America", "Vereinigte Staaten von Amerika", "États-Unis", "Estados Unidos"]
c.translations['fr'] #=> "États-Unis"

Subdivisions & States

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


c.latitude #=> "38 00 N"
c.longitude #=> "97 00 W"

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

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"

European Union Membership

c.in_eu? #=> false


Countries now uses the Currencies gem. What this means is you now get back a Currency object that gives you access to all the currency information. It acts the same as a hash so the same ['name'] methods still work.

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

If a country has an alternate currency it can be accessed via the alt_currency method and will also return a Currency object.

Since we are using the Currencies gem we get a bonus ExchangeBank that can be used with the Money gem. It auto loads exchange rates from Yahoo Finance.

Money.default_bank =
Money.us_dollar(100).exchange_to("CAD")  # =>, "CAD")

Address Formatting

A template for formatting addresses is available through the address_format method. These templates are compatible with the Liquid template system.

c.address_format #=> "{{recipient}}\n{{street}}\n{{city}} {{region}} {{postalcode}}\n{{country}}"


  • Mongoid support
  • State select
  • Class methods for looking up information
  • Default country
  • Exclude countries
  • Preferred countries
  • Whitelist countries

Note on Patches/Pull Requests

  • Fork the project.
  • Make your feature addition or bug fix.
  • Add tests for it. This is important so I don't break it in a future version unintentionally.
  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
  • Send me a pull request. Bonus points for topic branches.


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