Convert country names and codes, in R and Python

One shared dictionary, more than 40 coding schemes, and 600 country-name variants in dozens of languages.

install.packages("countrycode") pip install countrycode

Why

Different data sources code countries differently (CoW, ISO, and dozens more). Some schemes are less than intuitive, and merging data across them means converting from one scheme to another, or from long country names to a scheme.

countrycode() does that conversion from a dictionary shared by the R and Python packages. Regular-expression matching handles long country names such as “Sri Lanka,” and destination fields include regional groupings.

If you use countrycode in your research, we would be very grateful if you could cite our paper:

Arel-Bundock, Vincent, Nils Enevoldsen, and CJ Yetman, (2018). countrycode: An R package to convert country names and country codes. Journal of Open Source Software, 3(28), 848, https://doi.org/10.21105/joss.00848.

Install

Released versions come from CRAN and PyPI:

install.packages("countrycode")

pip install countrycode

Development versions come from this monorepo:

remotes::install_github("vincentarelbundock/countrycode/r")

pip install "countrycode @ git+https://github.com/vincentarelbundock/countrycode.git#subdirectory=python"

Usage

library(countrycode)

countrycode(
  c("Canada", "Algeria"),
  origin = "country.name",
  destination = "iso3c"
)
#> [1] "CAN" "DZA"

from countrycode import countrycode

countrycode(
    ["Canada", "Algeria"],
    origin="country.name",
    destination="iso3c",
)
# ['CAN', 'DZA']

Python also provides the higher-level helpers available in R:

from countrycode import countryname, guess_field

# Detect country names without first specifying their language.
countryname(["Sverige", "ジンバブエ"], destination="iso3c")
# ['SWE', 'ZWE']

# Identify a column's likely coding scheme.
guess_field(["DZA", "CAN", "DEU"])

countrycode() supports unmatched-value replacement, warnings, custom overrides, explicit regular-expression matching, and fallback destinations:

countrycode(
    ["Serbia", "Atlantis"],
    origin="country.name",
    destination=["cowc", "iso3c"],
    nomatch="Unknown",
)
# ['SRB', 'Unknown']

Codes

The R package documents the fields at ?codelist. In Python, inspect them with codelist.keys():

from countrycode import codelist

codelist.keys()

Country-year codes and the multilingual name dictionary are loaded on demand:

from countrycode import load_codelist_panel, load_countryname_dict

panel = load_codelist_panel()
names = load_countryname_dict()

Maintained custom dictionaries can be downloaded with get_dictionary():

from countrycode import get_dictionary

states = get_dictionary("us_states")
countrycode("MO", "state.abb", "state.name", custom_dict=states)
# 'Missouri'

Supported fields include:

• 600+ variants of country names in different languages and formats.
• Telephone
• AR5
• Continent and region identifiers.
• Correlates of War (numeric and character)
• European Central Bank
• EUROCONTROL — The European Organisation for the Safety of Air Navigation
• Eurostat
• Federal Information Processing Standard (FIPS)
• Food and Agriculture Organization of the United Nations
• Global Administrative Unit Layers (GAUL)
• Geopolitical Entities, Names and Codes (GENC)
• Gleditsch & Ward (numeric and character)
• International Civil Aviation Organization
• International Monetary Fund
• International Olympic Committee
• ISO (2/3-character and numeric)
• Polity IV
• United Nations
• United Nations Procurement Division
• Varieties of Democracy
• World Bank
• World Values Survey
• Unicode symbols (flags)

Cite

JOSS · CRAN · PyPI · GitHub