Countries

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 data used in this gem is also available as git submodules in YAML and JSON files.

Installation

 gem install countries

Or you can install via Bundler if you are using Rails:

bundle add countries

Basic Usage

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

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

Get all country codes (alpha2).

ISO3166::Country.codes
#  ["TJ", "JM", "HT",...]

Configuration

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 to 4.2 and 5.x

Release 4.2.0 introduced changes to name attributes and finders and deprecated several methods to resolve some existing confusion regardign official ISO country names vs. the "common names" that are commonly used.

The 5.0 release removed these deprecated methods and also removed support for Ruby 2.5 and 2.6

Please see UPGRADE.md for more information

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    = ISO3166::Country.find_country_by_iso_short_name('italy')
c    = ISO3166::Country.find_country_by_any_name('united states')
h    = ISO3166::Country.find_all_by(:translated_names, 'França')
list = ISO3166::Country.find_all_countries_by_region('Americas')
c    = ISO3166::Country.find_country_by_alpha2("FR")

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

Please note that find_by_name, find_by_names, find_*_by_name and find_*_by_names methods were removed in 5.0. See UPGRADE.md for more information

Country Info

Identification Codes

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

Names & Translations

c.iso_long_name # => "The United States of America"
c.iso_short_name # => "United States of America"
c.iso_short_name_lower_case # => "United States of America (the)"
c.common_name # => "United States" (This is a shortcut for c.translations('en'))
c.unofficial_names # => ["United States of America", "Vereinigte Staaten von Amerika", "États-Unis", "Estados Unidos"]

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

# Get a specific translation
# `translation` method works with string or symbol locales
c.translation('de') # => 'Vereinigte Staaten von Amerika'
c.translation(:de) # => 'Vereinigte Staaten von Amerika'
# `translations` method returns a symbol-keyed hash of translations
c.translations[:fr] # => "États-Unis"

# Get all translations for a locale, defaults to 'en'
ISO3166::Country.translations         # {"de:"Germany",...}
ISO3166::Country.translations('de')   # {"DE"=>"Deutschland",...}
ISO3166::Country.all_translated       # ['Germany', ...]
q # ['Deutschland', ...]

# Nationality
c.nationality # => "American"

Subdivisions & States

c.subdivisions # => {"CO" => {"name" => "Colorado", "names" => "Colorado"}, ... }
c.subdivision_types # => ["state", "outlying_area", "district"]
c.subdivisions_of_types(['state']) # => {"CO" => {"name" => "Colorado", "names" => "Colorado"}, ... }
c.humanized_subdivision_types # => ["State", "Outlying area", "District"]

# This is now deprecated. #states is an alias of #subdivisions and returns all subdivisions regardless of type
c.states # => {"CO" => {"name" => "Colorado", "names" => "Colorado"}, ... }


# Get specific translations for the country subdivisions
c.subdivision_names_with_codes('es') #=> [ ..., ["Nuevo Hampshire", "NH"], ["Nueva Jersey", "NJ"], ... ]

# Subdivision code with translations for all loaded locales
c.subdivisions['NY'].code_with_translations #=> {"NY"=>{"en"=>"New York"}, ...}

#find_subdivision_by_name Find a country's state using its code or name in any translation

> ISO3166::Country.new("IT").find_subdivision_by_name("Toscana").geo
 => {"latitude"=>43.771389, "longitude"=>11.254167, ... }
> ISO3166::Country.new("IT").find_subdivision_by_name("Tuscany").geo
 => {"latitude"=>43.771389, "longitude"=>11.254167, ... }

Location

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

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

Please note that latitude_dec and longitude_dec were deprecated on release 4.2 and removed in 5.0. These attributes have been redundant for several years, since the latitude and longitude fields have been switched decimal coordinates.

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](https://www.rubydoc.info/gems/tzinfo/TZInfo/CountryTimezone)
c.timezones # see [tzinfo docs](https://www.rubydoc.info/gems/tzinfo/TZInfo/Country)

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'

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

European Union Membership

c.in_eu? # => false

European Economic Area Membership

c.in_eea? # => false

European Single Market Membership

c.in_esm? # => false

EU VAT Area membership

c.in_eu_vat? # => false

UN membership

c.in_un? # false

GDPR Compliant (European Economic Area Membership or UK)

c.gdpr_compliant? # => false

Country Code in Emoji

c = Country['MY']
c.emoji_flag # => "🇲🇾"

Country Distance Unit (miles/kilometres)

c.distance_unit # => "MI"

Country Vehicle Registration Code

c.vehicle_registration_code # => "D"

Plucking multiple attributes

ISO3166::Country.pluck(:alpha2, :iso_short_name) # => [["AD", "Andorra"], ["AE", "United Arab Emirates"], ...

.collect_countries_with allows to collect various countries' information using any valid method and query value:

> ISO3166::Country.collect_countries_with("VR",:subdivisions,:common_name)
 => ["Italy", "Monaco"]
> ISO3166::Country.collect_countries_with("Caribbean",:subregion,:languages_spoken).flatten.uniq
 => ["en", "fr", "es", "ht", "nl"]
> ISO3166::Country.collect_countries_with("Oceania",:region,:international_prefix).uniq
 => ["00", "011", "0011", "19", "05"]
> ISO3166::Country.collect_countries_with("Antarctica",:continent,:emoji_flag)
 => ["🇦🇶", "🇬🇸", "🇧🇻", "🇹🇫", "🇭🇲"]
> ISO3166::Country.collect_countries_with("🇸🇨",:emoji_flag,:common_name)
 => ["Seychelles"]

.collect_likely_countries_by_subdivision_name allows to lookup all countries having the given state code or state name (in any translation)

ISO3166::Country.collect_likely_countries_by_subdivision_name("San José",:common_name)
 => ["Costa Rica", "Uruguay"]

Conversions

ISO3166::Country.from_alpha3_to_alpha2('USA') # => "US"
ISO3166::Country.from_alpha2_to_alpha3('US') # => "USA"

ISO3166::Country.from_alpha2_to_alpha3('--') # => nil

Currencies

To enable currencies extension please add the following to countries initializer.

ISO3166.configuration.enable_currency_extension!

Please note that it requires you to add "money" dependency to your gemfile.

gem "money", "~> 6.9"

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 = ISO3166::Country['us']
c.currency.iso_code # => 'USD'
c.currency.name # => 'United States Dollar'
c.currency.symbol # => '$'

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}}"

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 its supported