countrycodes is a dependency-free Python library for looking up all 249 ISO 3166-1 countries and territories, including continent assignments and international dial codes where available.

Installation

pip install countrycodes

Requires Python 3.11 or newer.

Usage

import countrycodes as cc

united_states = cc.get_country("us")
print(united_states.alpha3)  # USA
print(united_states.numeric)  # 840
print(united_states.dial_code)  # +1

united_kingdom = cc.find_country("United Kingdom")
print(united_kingdom.alpha2)  # GB

typo_tolerant_match = cc.find_country("Untied States")
print(typo_tolerant_match.alpha2)  # US

print(len(cc.list_countries()))  # 249

try:
    cc.get_country("Atlantis")
except cc.CountryNotFoundError:
    print("No matching country")

Lookups accept alpha-2, alpha-3, and numeric codes, dial codes, and country names. Matching is case-insensitive and ignores surrounding or repeated whitespace. If there is no exact match, a sufficiently similar country name is matched as a typo-tolerant fallback. A dial code shared by multiple countries is ambiguous and raises ValueError. list_countries returns records sorted by alpha-2 code. find_country returns None when there is no match; get_country raises CountryNotFoundError. dial_code is the international country calling code, not a local area code, and is None when no code is available.

Data and licenses

The bundled country registry is an adapted subset of ISO 3166-1 data from the iso-codes project. Continent assignments are from GeoNames, using GeoNames' single-continent mapping for each country or territory. The registry data is licensed under LGPL-2.1-or-later, continent assignments under CC BY 4.0, and dial codes are derived from GeoNames countryInfo.txt, also under CC BY 4.0. The library code is under BSD 3-Clause. See the data notice, LGPL license text, and BSD license.