Skip to main content
The countrystatecity Python packages provide access to countries, states, and cities data with full type hints, Pydantic models, and lazy loading. All data is bundled directly — no API key or network requests needed.
Always install using the suffixed package name (e.g. countrystatecity-countries). There is no bare countrystatecity package on PyPI — pip install countrystatecity will not work.

Available Packages

PackageStatusDescription
countrystatecity-countriesReleasedCountries, states, and cities with lazy loading
countrystatecity-timezonesComing soonIANA timezone data and utilities
countrystatecity-currenciesComing soonCurrency codes, symbols, and formatting
countrystatecity-languagesComing soonLanguage codes and metadata
countrystatecity-phonecodesComing soonInternational dialing codes and validation

Installation

pip install countrystatecity-countries

Usage

Countries

from countrystatecity_countries import get_countries, get_country_by_code

countries = get_countries()
print(f"Total countries: {len(countries)}")

usa = get_country_by_code("US")
print(f"{usa.emoji} {usa.name}")
print(f"Capital: {usa.capital}")
print(f"Currency: {usa.currency_symbol} {usa.currency_name}")

States

from countrystatecity_countries import get_states_of_country

states = get_states_of_country("IN")
print(f"Total states in India: {len(states)}")

for state in states[:3]:
    print(f"{state.name} ({state.iso2})")
# Maharashtra (MH)
# Karnataka (KA)
# Tamil Nadu (TN)

Cities

from countrystatecity_countries import get_cities_of_state

cities = get_cities_of_state("US", "CA")
print(f"Cities in California: {len(cities)}")

for city in cities[:3]:
    print(f"{city.name}{city.latitude}, {city.longitude}")
# Los Angeles — 34.05223, -118.24368
# San Diego — 32.72541, -117.15726
# San Jose — 37.33939, -121.89496

Country Details

from countrystatecity_countries import get_country_by_code

gb = get_country_by_code("GB")
print(gb.name)           # United Kingdom
print(gb.iso2)           # GB
print(gb.iso3)           # GBR
print(gb.capital)        # London
print(gb.currency)       # GBP
print(gb.currency_name)  # British Pound
print(gb.region)         # Europe
print(gb.timezones)      # [...]

Features

Type-safe

Full type hints with Pydantic models and mypy support.

Lazy loading

Data loads on first access and caches with LRU cache for minimal memory footprint.

Zero dependencies

Only requires Pydantic — no other external packages.

Full coverage

250+ countries, 5,299+ states, 153,765+ cities with coordinates and metadata.

Data Updates

To get the latest geographical data, update the package:
pip install --upgrade countrystatecity-countries

Source

GitHub Repository

View source, open issues, or contribute.

PyPI

Browse the published package on PyPI.