search

sshaw / normalize_country

Convert country names and codes to a standard.
68 stars 8 forks source link
conversion country-codes country-flags emoji iso3166 ruby

readme

= NormalizeCountry

Convert country names and codes to a standard.

{Build Status}[https://travis-ci.org/sshaw/normalize_country] {}[https://codeclimate.com/github/sshaw/normalize_country]

=== 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}[https://www.ruby-lang.org]):

gem install normalize_country

{Bundler}[http://bundler.io]:

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}[http://sequel.jeremyevans.net/rdoc/classes/Sequel.html#method-c-connect]. 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}[http://rubygems.org/gems/faker] and {RandomData}[http://rubygems.org/gems/random_data] don't generate much country data. If you'd like to use this gem to do so I suggest checking out this gist: https://gist.github.com/sshaw/6068404

=== Faulty/Missing/Erroneous Country Names

Please submit a patch or {open an issue}[https://github.com/sshaw/normalize_country/issues].

=== 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:

=== See Also