countrycode for R and Python

countrycode is available for both R and Python. The two packages share the same country-code dictionary and convert country names and codes across more than 40 coding schemes and 600 country-name variants.

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

Why countrycode?

The Problem

Different data sources use different coding schemes to represent countries (e.g. CoW or ISO). This poses two main problems: (1) some of these coding schemes are less than intuitive, and (2) merging these data requires converting from one coding scheme to another, or from long country names to a coding scheme.

The Solution

The R and Python packages provide a countrycode() function backed by a shared dictionary. It converts between more than 40 country coding schemes and 600 country-name variants in different languages and formats. Regular-expression matching supports conversion from long country names such as “Sri Lanka,” and destination fields include regional groupings.

Installation

R

Install the released package from CRAN:

install.packages("countrycode")

Install the development version from this monorepo:

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

Python

Install the released package from PyPI:

pip install countrycode

Install the development version from this monorepo:

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

Usage

R

library(countrycode)

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

Python

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"])

The Python countrycode() function 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']

Supported 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)