Country Engine

A fast and efficient Python library for converting between various country code formats and names.

Features

• 🚀 Fast: Built on Polars for high-performance data operations
• 🔄 Comprehensive: Supports 50+ country code formats including ISO codes, regional classifications, and localized names
• 🎯 Smart: Automatic format detection and fuzzy name matching
• 💾 Efficient: LRU caching for optimal performance
• 📦 Easy to use: Simple API with just one main function

Installation

pip install country-engine

Quick Start

from country_engine import convert, Formats

# Convert country codes
convert("USA", to=Formats.ISO2C)  # Returns: "US"
convert("US", to=Formats.ISO3C)   # Returns: "USA"
convert("840", to=Formats.ISO3C)  # Returns: "USA"

# Convert country names
convert("United States", to=Formats.ISO2C)  # Returns: "US"
convert("France", to=Formats.ISO3N)         # Returns: "250"

# Explicit source format (faster)
convert("US", to=Formats.ISO3C, from_format=Formats.ISO2C)  # Returns: "USA"

# Multiple language support
convert("Deutschland", to=Formats.ISO2C)  # Returns: "DE"
convert("Japon", to=Formats.ISO3C)        # Returns: "JPN"

Supported Formats

The library supports a wide range of country code formats:

ISO Standards

• Formats.ISO2C - ISO 3166-1 alpha-2 (e.g., "US")
• Formats.ISO3C - ISO 3166-1 alpha-3 (e.g., "USA")
• Formats.ISO3N - ISO 3166-1 numeric (e.g., "840")

Country Names

• Formats.Country.Name.EN - English names
• Formats.Country.Name.FR - French names
• Formats.Country.Name.DE - German names
• Formats.Country.Name.IT - Italian names

Regional Classifications

• Formats.CONTINENT - Continent names
• Formats.REGION - UN regions
• Formats.EU28 - EU28 membership

International Organizations

• Formats.UN - United Nations codes
• Formats.WB - World Bank codes
• Formats.IMF - International Monetary Fund codes
• Formats.FAO - Food and Agriculture Organization codes

And many more...

• CLDR localized names in 200+ languages/locales
• Currency codes (ISO 4217)
• Top-level domains
• IOC Olympic codes
• FIPS codes
• And 40+ additional formats

API Reference

convert(value, to, from_format=None)

Convert a country code or name to a specific target format.

Parameters:

• value (str | int): The input country code or name
• to (str): The target format identifier (from Formats class)
• from_format (str, optional): Explicit format of the input. If None, the function attempts to infer it.

Returns:

• str | None: The converted value as a string, or None if conversion failed

Example:

# Auto-detect input format
result = convert("USA", to=Formats.ISO2C)

# Specify input format for better performance
result = convert("USA", to=Formats.ISO2C, from_format=Formats.ISO3C)

Performance

Country Engine is designed for high performance:

• Lazy loading: Data files are only loaded when needed
• Caching: LRU caching for frequently used conversions
• Efficient data structures: Polars DataFrames for fast lookups
• Pre-built search index: Fast format inference

Development

Install for development

git clone https://github.com/EledoneAi/country-engine.git
cd country-engine
pip install -e .

Data Sources

The library uses data compiled from multiple authoritative sources:

• ISO 3166-1 standard
• Unicode CLDR project
• United Nations statistics
• World Bank data
• And other international organizations

The country data is sourced from pycountrycode by Vincent Arel-Bundock, which provides a comprehensive compilation of country codes and classifications.

License

MIT License - see LICENSE file for details

Acknowledgments

• Built with Polars for high-performance data operations
• Country data sourced from pycountrycode by Vincent Arel-Bundock
• Country data compiled from various international standards and organizations