country-converter

What it is and what it does

Country converter (coco) is a Python package that standardizes and matches country names across multiple classification schemes. It solves the problem of inconsistent country naming in datasets by converting between ISO 2-letter codes, ISO 3-letter codes, ISO numeric codes, and common country names. Internally, it uses regex patterns to match variants and stores data in a pandas DataFrame, making it useful for data cleaning and aggregation tasks.

The package includes built-in classifications for UN membership, EU membership, OECD membership, UN regions, continents, and various MRIO and IAM databases. It offers both a Python API and a command-line interface. For pandas Series, a dedicated `pandas_convert()` method provides significant performance gains (described as 4000x speedup for 1 million rows compared to the standard convert method). You can also access the underlying DataFrame directly to filter by membership criteria or build custom concordance matrices.

Use it for:

• Clean messy country names in datasets by converting them to standardized ISO codes or short names.
• Filter datasets by country membership in organizations like the EU, OECD, or UN by year.
• Build concordance matrices to map between different country classification schemes used in different data sources.
• Batch-convert large pandas Series of country identifiers to a target format with high performance.
• Match country names from one list against a master list using regex-based fuzzy matching.
• Extract country-level data from multi-source datasets where countries are named inconsistently.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Converts and matches country names across different classification standards (ISO 2/3 letter codes, numeric codes, UN/EU/OECD membership schemes) using regex-based matching and can build concordance matrices between schemes.

Yes, with conditions. The package is well-maintained enough for production use (no known vulnerabilities, active repository, supports current Python versions), but its aging maintenance status (296 days since last release) means you should monitor for updates. The GPLv3 license is a hard blocker if you need to keep your code proprietary. Install it if you regularly work with messy country data and can accept the copyleft requirement.

Install

country-converter on PyPI

pip install country-converter

uv add country-converter

poetry add country-converter

Installing country-converter

Before you install

Low install friction with a single runtime dependency on pandas. Maintenance status is aging—the last release was 296 days ago, though the repository remains active with recent commits and no archived status.

License in practice

Licensed under GPLv3 (copyleft). Any derivative work or distribution must also be licensed under GPLv3; proprietary applications cannot incorporate this package without open-sourcing their own code.

Quickstart

pip install country_converter

import country_converter as coco
cc = coco.CountryConverter()
standard_names = cc.convert(names=['DE', 'France', 'USA'], to='name_short')
print(standard_names)

Requires Python 3.9 or later (supports 3.9–3.13); pandas must be installed as a runtime dependency.

Verify before relying

• Whether the regex-based matching handles all edge cases and non-English country name variants reliably.
• Performance characteristics for very large datasets beyond the 1 million-row example mentioned in the description.

Package facts

Evidence: country_converter-1.3.2-py3-none-any.whl

Keywords: country, ISO 3166

Tags

More Scientific/Engineering packages