Country Converter (coco)

1.3.2 · active · verified Sat Apr 11

The country converter (coco) is a Python package designed to convert and match country names between various classification schemes and different naming conventions. It leverages regular expressions for robust matching and supports a wide array of classifications, including ISO, UN, EU, OECD, FIFA, IOC, continents, and several MRIO/IAM databases. The current version is 1.3.2, and it typically sees several updates per year to enhance classifications and features.

Warnings

breaking Prior to version 1.0.0, and specifically in v0.7.6, the library made a breaking change requiring additional custom data to explicitly specify the 'ISO2' classification for regex matching. Updates from pre-1.0 versions may require code adjustments if custom data was used.
Fix: Ensure any custom country data provided to `country-converter` includes an 'ISO2' column with appropriate values for matching, especially if upgrading from versions prior to 0.7.6.
gotcha By default, `country-converter` logs a warning to the Python logging logger if no match is found for a given country name during conversion. This can lead to silently missed conversions if log outputs are not monitored.
Fix: Monitor the Python logging output for `country_converter` warnings, or explicitly handle `None` (or the original unmatched input) in the results. For finer control, you can configure the logging behavior or specify `not_found='keep'` or `not_found='raise'` in the `convert` method to either retain the original input or raise an error.
gotcha When converting country names, if the input format is ambiguous (e.g., 'US' could be 'ISO2' or a short name), the library attempts to automatically determine the source format. This auto-detection might occasionally lead to incorrect conversions for ambiguous inputs.
Fix: For ambiguous country names or when certainty is required, explicitly specify the source classification using the `src` parameter in the `convert` method (e.g., `coco.convert(names='US', src='ISO2', to='ISO3')`).

Install

pip install country-converter Install with pip

Imports

CountryConverter
```
import country_converter as coco
```

Quickstart

This quickstart demonstrates how to import the `country_converter` library and use its `convert` function to transform country names between different classification schemes like ISO2, ISO3, and various continent classifications.

import country_converter as coco

# Convert a single country name to its ISO3 code
iso3_code = coco.convert(names='Germany', to='ISO3')
print(f"The ISO3 code for Germany is: {iso3_code}")

# Convert a list of country names to ISO2 codes
country_names = ['France', 'Italy', 'Spain']
iso2_codes = coco.convert(names=country_names, to='ISO2')
print(f"The ISO2 codes for {country_names} are: {iso2_codes}")

# Convert a country name to its continent (7-continent classification)
continent = coco.convert(names='Brazil', to='Continent7')
print(f"Brazil is in: {continent}")

view raw JSON →