{"id":2903,"library":"country-converter","title":"Country Converter (coco)","description":"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.","status":"active","version":"1.3.2","language":"en","source_language":"en","source_url":"https://github.com/IndEcol/country_converter","tags":["country codes","data conversion","classification","ISO","UN","EU"],"install":[{"cmd":"pip install country-converter","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Used internally for data storage and efficient Series conversion.","package":"pandas","optional":false},{"reason":"Provides access to official ISO databases for country information.","package":"pycountry","optional":false}],"imports":[{"symbol":"CountryConverter","correct":"import country_converter as coco"}],"quickstart":{"code":"import country_converter as coco\n\n# Convert a single country name to its ISO3 code\niso3_code = coco.convert(names='Germany', to='ISO3')\nprint(f\"The ISO3 code for Germany is: {iso3_code}\")\n\n# Convert a list of country names to ISO2 codes\ncountry_names = ['France', 'Italy', 'Spain']\niso2_codes = coco.convert(names=country_names, to='ISO2')\nprint(f\"The ISO2 codes for {country_names} are: {iso2_codes}\")\n\n# Convert a country name to its continent (7-continent classification)\ncontinent = coco.convert(names='Brazil', to='Continent7')\nprint(f\"Brazil is in: {continent}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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')`).","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}