Table of Contents

• Installation
• License
• Features
  • Why
• Usage
  • Country Based Interface
  • Subdivision Based Interface
• Roadmap

pip install simpleiso3166

For the searching by partial name, include the extra:

pip install simpleiso3166[search]

simpleiso3166 is distributed under the terms of the MPL-2.0 license.

• Strongly typed interface to ISO 3166-1 countries and ISO 3166-2 subdivisions (e.g. states, provinces)
• No JSON parsing at runtime, fully defined in Python
• Includes defined types to allow integration with libraries like Pydantic for validation of code validity
• Lazy loading of subdivision data on demand for reduced memory usage
• Searching for countries by exact or partial name
• Searching for subdivisions by exact or partial name
• Supports Python 3.9+
• On Python 3.10 and newer, uses slots to efficiently store country and subdivision data

This library was created as a way to provide strongly typed access to the ISO 3166 standard, which is used to define country codes and subdivision codes. It's designed to be lightweight and easy to use in Python projects.

Other existing libraries include pycountry, but they don't provide the same strongly typed interface as this library does. They also load JSON files at runtime, which can be a performance issue and takes memory.

If you know the country's code:

country = Country.from_alpha2("US")

assert country.name == "United States of America"
assert country.common_name == "United States"

# Subdivision data isn't loaded until the first ask for it
assert len(list(country.subdivisions)) == 57

If you need to search for the country:

results = list(Country.from_partial_name("Kingdom"))

assert len(results) == 17
assert results[0].alpha2 == "BE"
assert results[0].name == "Kingdom of Belgium"
assert results[0].common_name == "Belgium"

assert results[10].alpha2 == "NL"
assert results[10].name == "Kingdom of the Netherlands"
assert results[10].common_name == "Netherlands"

assert results[16].alpha2 == "TO"
assert results[16].name == "Kingdom of Tonga"
assert results[16].common_name == "Tonga"

Access a particular subdivision:

country = Country.from_alpha2("DE")

# You can check this subdivision code is in this country
assert country.contains_subdivision("DE-BW")

# This will return None if the subdivision isn't valid
subdivision = country.get_subdivision("DE-BW")
assert subdivision.name == "Baden-Württemberg"

Search for a subdivision by name. This will have to load ALL subdivision data though:

results = list(Subdivision.search_by_name("Connecticut"))

assert len(results) == 1
assert results[0] == "US-CT"

This is partly implemented, but more aliases would be helpful

• Search using common aliases for countries (e.g. "USA" for "United States of America")
• Extended searching for subdivisions by common aliases (eg "DC" for "Washington DC")
• Search using re-ordered names (e.g. "The Democratic Republic of the Congo" for instead of "Congo, The Democratic Republic of the")

• Access to deleted country data