Convert country codes or names from one format to another.

def countrycode(
  sourcevar: Any,
  origin: str,
  destination: str | Sequence[str],
  custom_dict: Any = None,
  *,
  warn: bool = True,
  nomatch: Any = _DEFAULT_NOMATCH,
  custom_match: Mapping[Any, Any] | None = None,
  origin_regex: bool | None = None
)

Description

Converts long country names into coding schemes, translates between schemes, standardizes country names, and identifies continents or regions. The built-in conversion dictionary supports ISO, Correlates of War, Gleditsch-Ward, World Bank, Unicode flag, and many other fields.

Multiple destinations are tried from left to right. Each destination fills values not covered by an earlier one. Country-name origins use regular expressions; other built-in origins use case-insensitive exact matching.

Arguments

`sourcevar`	Country codes or names to convert. Accepts a scalar, list, tuple, Pandas Series, Polars Series, or another iterable.
`origin`	Name of the source coding scheme, such as `"iso3c"` or `"country.name"`.
`destination`	Destination coding scheme, or a sequence of schemes to try in order, such as `["cowc", "iso3c"]`.
`custom_dict`	Optional replacement dictionary. Accepts a mapping of column names to equal-length sequences, a Pandas or Polars DataFrame, or a path to a `.csv` or `.csv.gz` file.
`warn`	Emit warnings listing unmatched or ambiguous input values.
`nomatch`	Replacement for unmatched values. By default they become `None`. Pass `None` to preserve the original inputs, a scalar to use one replacement, or a sequence matching `sourcevar`.
`custom_match`	Mapping of input values to destination values. These overrides supersede normal or ambiguous matches.
`origin_regex`	Whether the origin column contains regular expressions. The default selects regex matching for built-in country-name origins and exact matching otherwise.

Value

Converted values. A scalar input returns a scalar; lists and tuples retain their container kind; Pandas and Polars Series retain their respective type and metadata where applicable.

Raises

`TypeError`	If `origin`, `destination`, or `sourcevar` has an unsupported shape or type.
`ValueError`	If a code field is invalid, a numeric origin receives non-numeric input, the custom dictionary is malformed, or `nomatch` has an incompatible length.
`FileNotFoundError`	If a custom dictionary path does not exist.
`NotImplementedError`	If a custom dictionary type or file format is unsupported.

Notes

Country-year data require special care because some political units, including Vietnam and Serbia, change codes over time. For panel data, prefer countrycode.datasets.load_codelist_panel and merge on the appropriate year instead of relying on the cross-sectional dictionary.

Examples

countrycode(["USA", "DZA"], "iso3c", "cown")
countrycode("Albania", "country.name", "iso3c")
countrycode("Serbia", "country.name", ["cowc", "iso3c"], warn=False)