A common list of countries

Having an agreed list of country names including a mapping to alpha-3 and alpha-2 codes (also know as ISO3 and ISO2 codes) is an important prerequisite for scenario analysis and model comparison.

The nomenclature package builds on the pycountry package (link) to provide a utility for country names based on the ISO 3166-1 standard.

For consistency with established conventions in the modelling community, several country names are shortened compared to ISO 3166-1, e.g. from “Bolivia, Plurinational State of” to “Bolivia”. Also, “Kosovo” is added (with alpha_3 code “KOS”, following the IOC), even though it is not a universally recognized state and not oficially included in ISO 3166-1. See the full list of changes on GitHub.

You can access the list of countries via the model registration Excel template.

You can also use this utility for mapping between country names as used in the community and alpha-3 or alpha-2 codes, as shown in this example.

from nomenclature import countries

# list of country names
countries.names

# mappings between ISO3 (alpha_3), alpha_2 and country names
name = countries.get(alpha_3="...").name
alpha_3 = countries.get(name="...").alpha_3
alpha_2 = countries.get(name="...").alpha_2

class nomenclature.countries.Countries

List of countries based on simplified ISO 3166 database

This list follows the nomenclature.countries module based on country names using ISO 3166-1, but it simplifies several country names for readability and in line with conventions of the IAMC community.

Attributes:

names

Methods

get(**kwargs)	Get a specific country by attribute
get_mapping(from_attr, to_attr)	Get a mapping from one country attribute to another

get(**kwargs)

Get a specific country by attribute

Parameters:

namestr

Country name

alpha_3str

Alpha-3 code (ISO3)

alpha_2str

Alpha-2 code (ISO2)

Returns:

pycountry.db.Country

get_mapping(from_attr, to_attr)

Get a mapping from one country attribute to another

Parameters:

from_attrstr

Source attribute (one of “name”, “alpha_3”, “alpha_2”)

to_attrstr

Target attribute (one of “name”, “alpha_3”, “alpha_2”)

Returns:

dict

Mapping from source attribute to target attribute for all countries

Examples

>>> countries.get_mapping("alpha_3", "name")
{'USA': 'United States', 'DEU': 'Germany', ...}

>>> countries.get_mapping("alpha_2", "alpha_3")
{'US': 'USA', 'DE': 'DEU', ...}