Convert Country Names to ISO 3166-1 Codes in Python: A 2026 Guide

Working with country names and converting them to their standard ISO 3166-1 alpha-2 codes can be essential when dealing with global datasets. This tutorial will guide you through the process of converting country names to ISO codes using Python, which is crucial for data normalization and integration in international applications.

Key Takeaways

• Learn to convert country names to ISO 3166-1 alpha-2 codes using Python.
• Understand the use of libraries like `pycountry` for efficient conversion.
• Get hands-on with practical code examples and troubleshooting tips.
• Discover how to handle common errors in data conversion.

When working with international data, standardizing country names using ISO codes ensures consistency and accuracy across datasets. This becomes particularly important in applications involving geographical data, international trade, and global analytics.

Prerequisites

Before diving into the tutorial, ensure you have the following:

• Basic understanding of Python programming.
• Python installed on your machine (version 3.7 or higher).
• Access to a terminal or command line interface.
• Pip for installing Python packages.

Step 1: Install Required Python Libraries

First, you need to install the `pycountry` library, which provides the ISO 3166-1 alpha-2 country codes. Open your terminal and run:

pip install pycountry

Ensure that the installation is successful by executing:

import pycountry

Step 2: Create a Function to Convert Country Names

Next, we'll create a Python function that takes a list of country names and returns a list of corresponding ISO 3166-1 alpha-2 codes.

import pycountry

# Function to convert country names to ISO 3166-1 alpha-2 codes
def convert_country_names_to_iso(countries):
    iso_codes = []
    for country in countries:
        try:
            # Lookup the country in the pycountry database
            country_data = pycountry.countries.lookup(country)
            iso_codes.append(country_data.alpha_2)
        except LookupError:
            # If the country is not found, append None or handle as needed
            iso_codes.append(None)
            print(f"Warning: {country} not found")
    return iso_codes

# Example usage
countries = ['American Samoa', 'Canada', 'France']
iso_codes = convert_country_names_to_iso(countries)
print(iso_codes)  # Output: ['AS', 'CA', 'FR']

This function uses the `pycountry.countries.lookup()` method to find the ISO code for each country. If a country cannot be found, it appends `None` and prints a warning.

Step 3: Handle Missing or Incorrect Country Names

Sometimes, the list of country names might have typos or non-standard names. You can improve the robustness of your function by handling these cases.

def robust_convert_country_names_to_iso(countries):
    iso_codes = []
    for country in countries:
        try:
            # Attempt multiple lookups with variations
            country_data = pycountry.countries.lookup(country)
            iso_codes.append(country_data.alpha_2)
        except LookupError:
            # Attempt to clean and retry
            cleaned_country = country.strip().title()
            try:
                country_data = pycountry.countries.lookup(cleaned_country)
                iso_codes.append(country_data.alpha_2)
            except LookupError:
                iso_codes.append(None)
                print(f"Error: Could not find ISO code for {country}")
    return iso_codes

This function attempts to fix minor issues by stripping whitespace and capitalizing the country names before a second lookup attempt.

Step 4: Validate the Conversion Output

Once the conversion function is in place, validate its output by comparing with known ISO codes. This ensures the accuracy of your conversion logic.

# Test the conversion
countries_test = ['United States', 'Brazil', 'India']
expected_output = ['US', 'BR', 'IN']
actual_output = robust_convert_country_names_to_iso(countries_test)

assert actual_output == expected_output, "Conversion did not match expected output"
print("All tests passed!")

Common Errors/Troubleshooting

Here are some common errors you might encounter and how to fix them:

• LookupError: Occurs when a country name is not found. Ensure names are correct or use variants.
• ImportError: If `pycountry` is not installed correctly, try reinstalling with pip.

By following these steps, you can effectively convert country names to ISO 3166-1 alpha-2 codes using Python, making your applications robust and globally compatible.

Frequently Asked Questions

What is ISO 3166-1?

ISO 3166-1 is part of the ISO 3166 standard for country codes, defining codes for the names of countries, dependent territories, and special areas of geographical interest.

Why use ISO codes for country names?

Using ISO codes ensures consistency and standardization in data handling, making it easier to integrate and compare global datasets.

What if a country name is not found?

If a country name isn't found, check for typos or use alternatives. You can also implement error handling to manage such cases.

Can I use this method for other ISO codes?

Yes, the approach can be adapted for other ISO code standards by using appropriate libraries and methods for lookup.