NormalizeCountry¶ ↑

Convert country names and codes to a standard.

<img src=“https://travis-ci.org/sshaw/normalize_country.svg?branch=master” alt=“Build Status” /> <img src=“https://codeclimate.com/github/sshaw/normalize_country.svg” />

Overview¶ ↑

require "normalize_country"

NormalizeCountry("America")                       # "United States"
NormalizeCountry("United States of America")      # "United States"
NormalizeCountry("USA",  :to => :official)        # "United States of America"
NormalizeCountry("Iran", :to => :official)        # "Islamic Republic of Iran"
NormalizeCountry("U.S.", :to => :alpha2)          # "US"
NormalizeCountry("U.S.", :to => :numeric)         # "840"
NormalizeCountry("US",   :to => :fifa)            # "USA"
NormalizeCountry("US",   :to => :emoji)           # "🇺🇸"
NormalizeCountry("US",   :to => :shortcode)       # ":flag-us:"
NormalizeCountry("Iran", :to => :alpha3)          # "IRN"
NormalizeCountry("Iran", :to => :ioc)             # "IRI"
NormalizeCountry("DPRK", :to => :short)           # "North Korea"
NormalizeCountry("North Korea", :to => :iso_name) # "Korea, Democratic People's Republic Of"

# Or
NormalizeCountry.convert("U.S.", :to => :alpha2)  # "US"

# Set the default
NormalizeCountry.to = :alpha3
NormalizeCountry.convert("Mexico")                 # "MEX"
NormalizeCountry.convert("United Mexican States")  # "MEX"

Installation¶ ↑

Rubygems (part of Ruby):

gem install normalize_country

Bundler:

gem "normalize_country"

Supported Conversions¶ ↑

In addition to trying to convert from common, non-standardized names and abbrivations, NormalizeCountry will convert to/from the following:

:alpha2

ISO 3166-1 alpha-2

:alpha3

ISO 3166-1 alpha-3

:emoji

The country’s emoji

:fifa

FIFA (International Federation of Association Football)

:ioc

International Olympic Committee

:iso_name

Country name used by ISO 3166-1

:numeric

ISO 3166-1 numeric code

:official

The country’s official name

:short

A shortned version of the country’s name, commonly used when speaking and/or writing (US English)

:shortcode:

Emoji shortcode

A list of valid formats can be obtained by calling NormalizeCountry.formats.

Obtaining an Array or Hash¶ ↑

NormalizeCountry.to_a                              # Defaults to NormalizeCountry.to
NormalizeCountry.to_a(:ioc)                        # Array of IOC codes in ascending order
NormalizeCountry.to_h(:ioc)                        # :ioc => NormalizeCountry.to
NormalizeCountry.to_h(:ioc, :to => :numeric)       # :ioc => :numeric

Conversion Utility¶ ↑

A small script is included that can convert country names contained in a DB table or a set of XML or CSV files

shell > normalize_country -h
usage: normalize_country [options] SOURCE
    -h, --help                       Show this message
    -f, --format FORMAT              The format of SOURCE
    -t, --to CONVERSION              Convert country names to this format (see docs for valid formats)
    -l, --location LOCATION          The location of the conversion

Some examples

normalize_country -t alpha2 -l 'Country Name' -f csv data.csv
normalize_country -t numeric -l countries.code -f db postgres://usr:pass@localhost/conquests
normalize_country -t fifa -l //teams[@sport = 'fútbol americano']//country -f xml data.xml

If the format is xml or csv you can spefify a directory instead of a filename

normalize_country -t alpha2 -l 'Country Name' -f csv /home/sshaw/capital-losses/2008

With a format of csv it will read all files with an extension of csv or tsv. For csv and xml the original file(s) will be overwritten with new file(s) containing the converted country names.

To convert an XML file with namespaces just include the namespace prefix defined in the file in the XPath query (LOCATION).

The db format’s SOURCE argument must be a Sequel connection string. Here LOCATION is in the format table.column, which will be updated with the converted name.

Random Country Data for Your Tests¶ ↑

Random data generating gems like Faker and RandomData don’t generate much country data. If you’d like to use this gem to do so I suggest checking out this gist: gist.github.com/sshaw/6068404

Faulty/Missing/Erroneous Country Names¶ ↑

Please submit a patch or open an issue.

Why?¶ ↑

This code was -to some extent- part of a larger project that allowed users to perform a free-text search by country. Country names were stored in the DB by their ISO names.

Several years later at work we had to extract country names from a web service that didn’t standardize them. Sometimes they used UK, other times U.K. It then occured to me that this code could be useful outside of the original project. The web service was fixed but, nevertheless…

Somewhat Similar Gems¶ ↑

Upon further investigation I’ve found the following:

• Carmen: ISO country names and states/subdivisions

• countries ISO country names, states/subdivisions, currency, E.164 phone numbers and language translations

• country_codes ISO country names and currency data

• i18n_data: ISO country names in different languages, includes alpha codes

• ModelUN: Similar to this gem but with less support for conversion, it does include US states

See Also¶ ↑

• National Colors