countryinfo Python Library

You can install countryinfo using pip or poetry. The library supports optional extras for fuzzy lookup and Pydantic models.

Standard Installation

pip install countryinfo

Installation with Extras

Use these commands to include additional functionality:

• countryinfo[fuzzy]: Enables typo-tolerant country lookup.
• countryinfo[pydantic]: Provides Pydantic v2 typed models.
• countryinfo[all]: Installs all optional extras.

pip install "countryinfo[fuzzy]"
pip install "countryinfo[pydantic]"
pip install "countryinfo[all]"

Using Poetry

poetry add countryinfo
poetry add "countryinfo[fuzzy,pydantic]"

To use the library, import CountryInfo and initialize it with a country identifier. You can then call various methods to retrieve geographic and demographic data.

from countryinfo import CountryInfo

country = CountryInfo("Singapore")
print(country.capital())      # Singapore
print(country.iso(2))         # SG
print(country.population())   # 5469700
print(country.neighbors())    # [] — island, no land borders

The countryinfo models require Pydantic v2. To enable model support, install the package with the [pydantic] extra using pip.

pip install countryinfo[pydantic]

When performing lookups, be prepared to handle the following errors:

• CountryNotFoundError: Raised when a country name or code cannot be found. This is a subclass of LookupError.
• ValueError: Raised if None or an empty string is passed to the CountryInfo constructor.

from countryinfo import CountryInfo, CountryNotFoundError

try:
    country = CountryInfo("Xanadu")
except CountryNotFoundError as e:
    print(f"Error: {e}")

try:
    CountryInfo(None)
except ValueError:
    print("Invalid input")

The .info() method returns a dictionary containing all available metadata for the country, including ISO codes, area, borders, calling codes, capital, currencies, demonym, languages, coordinates, population, region, timezones, and links to Wikipedia/Google.

from countryinfo import CountryInfo

info = CountryInfo("Singapore").info()
# Returns a dict containing 'name', 'ISO', 'area', 'borders', etc.

Use these functions to perform bulk operations or searches across the entire dataset:

• all_countries(): Returns a list of all CountryInfo objects.
• filter_countries(**kwargs): Filters countries based on specific criteria. Supported keys are region, subregion, language, currency, border, calling_code, and tld. Multiple arguments are combined using AND logic.
• CountryInfo.all(): A classmethod that returns the raw data for all countries as a dictionary {lowercase_name: {...}, ...}.

from countryinfo import all_countries, filter_countries, CountryInfo

# Get all capitals
countries = all_countries()
capitals = [c.capital() for c in countries]

# Filter by region and currency
eurozone = filter_countries(region="Europe", currency="EUR")

# Get raw data
raw_data = CountryInfo.all()

The CountryInfo constructor accepts several case-insensitive identifiers to resolve a country. Supported identifiers include:

• English Name: CountryInfo("Singapore") or CountryInfo("singapore")
• ISO alpha-2: CountryInfo("SG")
• ISO alpha-3: CountryInfo("SGP")
• ISO numeric: CountryInfo("702") (string) or CountryInfo(702) (int)
• Native / Alternate Name: CountryInfo("Singapura")
• Full Official Name: CountryInfo("Republic of Singapore")

Error Handling

• Raises ValueError if no identifier is supplied.
• Raises CountryNotFoundError (which inherits from LookupError) if the identifier cannot be resolved to a known country.

from countryinfo import CountryInfo

# Examples of valid initialization
country = CountryInfo("Singapore")
country = CountryInfo("SG")
country = CountryInfo(702)

If you install the [pydantic] extra (pip install "countryinfo[pydantic]"), you can convert a CountryInfo instance into a Pydantic model for structured access and validation.

# Requires: pip install "countryinfo[pydantic]"
from countryinfo import CountryInfo

country = CountryInfo("Singapore")
model = country.model()

print(model.name)          # Singapore
print(model.iso.alpha2)    # SG
print(model.population)    # 5469700

You can convert a CountryInfo instance into a structured Pydantic model by calling the .model() method. This provides type-safe access to country attributes like capital and iso codes.

from countryinfo import CountryInfo

country = CountryInfo("Singapore")
model = country.model()
print(model.capital)   # Singapore
print(model.iso.alpha2)  # SG

The countryinfo command-line tool allows you to query country data directly from your terminal.

Common Commands:

• countryinfo <name/code>: Get full info for a country.
• countryinfo <name/code> --field <name>: Get a specific field (e.g., capital, iso, current_utc_offset).
• countryinfo --filter <key>=<value>: Filter countries (e.g., --filter region=Asia). Multiple filters can be combined.
• countryinfo <name/code> --json: Output the result in JSON format.

# Full info
countryinfo Singapore

# Specific field
countryinfo SG --field iso

# Filter and JSON output
countryinfo --filter region=Europe currency=EUR --json

The .info() method returns a comprehensive dictionary containing all available data for the country. This includes a generated google key for quick searching.

The returned dictionary follows the CountryInfoDict schema, which includes fields like ISO, altSpellings, area, borders, capital, currencies, languages, latlng, population, region, timezones, and more.

from countryinfo import CountryInfo

country = CountryInfo("Singapore")
data = country.info()
print(data['name'])      # Singapore
print(data['ISO'])      # {'alpha2': 'SG', 'alpha3': 'SGP', 'numeric': '702'}
print(data['google'])   # https://www.google.com/search?q=Singapore