Country State City PyPI Packages

Official, versioned Python packages for offline access to Country State City data with type hints and lazy loading.

📦 Available Packages

Package	PyPI	Description
countrystatecity-countries		250 countries, 5,308 states, and 171,938 cities
countrystatecity-timezones		432 IANA timezones and time conversion utilities
countrystatecity-currencies		249 country/currency associations
countrystatecity-translations		4,724 country-name translations in 19 languages
countrystatecity-phonecodes		International phone/dialing codes for 250 countries
countrystatecity-regions		Region and subregion associations for 250 countries
countrystatecity-postal-codes		Postal/ZIP records for 125 countries

Note: There is no bare countrystatecity package on PyPI. Always install with the suffix (-countries, -timezones, -currencies, -translations, -phonecodes, -regions, -postal-codes).

From offline prototype to production

These packages provide versioned snapshots for offline use, development, and repeatable builds. For production applications that need regularly updated data, server-side search and filtering, field-selected responses, or managed availability and support, use the Country State City API.

Get a free API key · Read the API docs · Compare plans · Migration guide

API keys must stay in server-side environment variables, never in browser code or source control.

🚀 Installation

Install only what you need:

pip install countrystatecity-countries
pip install countrystatecity-timezones
pip install countrystatecity-currencies
pip install countrystatecity-translations
pip install countrystatecity-phonecodes
pip install countrystatecity-regions
pip install countrystatecity-postal-codes

📖 Usage

Countries

from countrystatecity_countries import (
    get_countries,
    get_country_by_code,
    get_states_of_country,
    get_cities_of_state,
)

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

# Specific country
usa = get_country_by_code("US")
print(f"{usa.emoji} {usa.name} — {usa.capital}")
print(f"Currency: {usa.currency_symbol} {usa.currency_name}")

# States and cities (lazy loaded)
states = get_states_of_country("US")
cities = get_cities_of_state("US", "CA")

Timezones

from countrystatecity_timezones import (
    get_all_timezones,
    get_timezones_by_country,
    get_timezone_by_zone_name,
    get_timezones_by_offset,
    convert_time,
)

# Timezones for a country
timezones = get_timezones_by_country("US")

# Lookup by zone name
tz = get_timezone_by_zone_name("America/New_York")
print(f"{tz.zone_name} — {tz.gmt_offset_name}")

# Convert time between zones
from datetime import datetime
dt = datetime(2024, 1, 1, 12, 0, 0)
converted = convert_time(dt, "America/New_York", "Asia/Kolkata")

Currencies

from countrystatecity_currencies import (
    get_all_currencies,
    get_currency_by_country,
    get_countries_by_currency,
    search_currencies,
)

# Currency for a country
currency = get_currency_by_country("US")
print(f"{currency.symbol} {currency.name} ({currency.code})")

# All countries using a currency
countries = get_countries_by_currency("EUR")

# Search
results = search_currencies("dollar")

Phone Codes

from countrystatecity_phonecodes import (
    get_all_phonecodes,
    get_phonecode_by_country,
    get_countries_by_phonecode,
    search_phonecodes,
)

# Phone code for a country
us = get_phonecode_by_country("US")
print(f"+{us.phoneCode} — {us.countryName}")  # +1 — United States

# All countries sharing a dialing code
plus1 = get_countries_by_phonecode("1")
print(f"{len(plus1)} countries use +1")

# Works with or without + prefix
plus44 = get_countries_by_phonecode("+44")

# Search
results = search_phonecodes("united")

Translations

from countrystatecity_translations import (
    get_all_translations,
    get_translations_by_country,
    get_translations_by_language,
    get_translation,
    search_translations,
)

# Country name in a specific language
translation = get_translation("US", "fr")
print(translation.name)  # États-Unis

# All translations for a country
translations = get_translations_by_country("IN")

# All countries translated in Japanese
japanese = get_translations_by_language("ja")

Regions

from countrystatecity_regions import (
    get_region_by_country,
    get_countries_by_region,
    get_countries_by_subregion,
    get_all_region_names,
    search_regions,
)

# Region/subregion for a country
region = get_region_by_country("US")
print(f"{region.region} — {region.subregion}")  # Americas — Northern America

# All countries in a region
asian_countries = get_countries_by_region("Asia")

# All countries in a subregion
south_asia = get_countries_by_subregion("Southern Asia")

# List distinct regions
print(get_all_region_names())  # ['Africa', 'Americas', 'Asia', 'Europe', 'Oceania', 'Polar']

# Search
results = search_regions("southern asia")

Postal Codes

from countrystatecity_postal_codes import (
    get_postal_info_by_country,
    get_postcodes_of_country,
    validate_postcode,
)

# Postal code format/regex for a country
us_info = get_postal_info_by_country("US")
print(us_info.postalCodeFormat)  # #####-####

# Validate a postcode against the country's known format
validate_postcode("US", "10001")  # True

# All postcodes for a country (lazy loaded)
postcodes = get_postcodes_of_country("AD")

✨ Features

• ✅ Type-safe with Pydantic models and mypy strict mode
• ✅ Lazy loading for minimal memory footprint
• ✅ 250 countries with metadata
• ✅ 5,308 states/provinces
• ✅ 171,938 cities
• ✅ 432 timezones with GMT offsets and time conversion
• ✅ 249 country/currency associations
• ✅ 4,724 translations in 19 languages
• ✅ Phone/dialing codes for 250 countries
• ✅ Regions and subregions for 250 countries
• ✅ 844,248 postal/ZIP-code records across 125 countries, with validation regexes for 189
• ✅ Zero external dependencies (except Pydantic)
• ✅ Python 3.8–3.12 support
• ✅ Full test coverage with pytest

🏗️ Repository Structure

countrystatecity-pypi/
├── python/
│   └── packages/
│       ├── countries/     # countrystatecity-countries
│       ├── timezones/     # countrystatecity-timezones
│       ├── currencies/    # countrystatecity-currencies
│       ├── translations/  # countrystatecity-translations
│       ├── phonecodes/    # countrystatecity-phonecodes
│       ├── regions/       # countrystatecity-regions
│       └── postal_codes/  # countrystatecity-postal-codes
│
└── .github/
    └── workflows/
        ├── python-ci.yml    # CI — tests, type check, lint
        ├── publish.yml      # Publish to PyPI
        ├── release.yml      # Version bump + changelog
        └── update-data.yml  # Weekly data sync

🛠️ Development

git clone https://github.com/dr5hn/countrystatecity-pypi.git

# Install a package in dev mode (replace 'countries' with any package)
cd python/packages/countries
pip install -e ".[dev]"

# Run tests
pytest --cov=countrystatecity_countries --cov-report=html

# Type check
mypy countrystatecity_countries/ --strict

# Lint and format
ruff check countrystatecity_countries/ tests/
black countrystatecity_countries/ tests/
isort countrystatecity_countries/ tests/

📊 Technology Stack

Component	Technology
Type System	Pydantic
Testing	pytest
Type Checking	mypy (strict)
Formatting	black + isort
Linting	ruff
CI/CD	GitHub Actions

📝 License

All packages are licensed under the Open Database License (ODbL-1.0).

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Run tests (pytest)
4. Commit your changes (git commit -m 'Add amazing feature')
5. Open a Pull Request

📞 Support

• Issues: GitHub Issues
• Website: countrystatecity.in
• Production API: Get a free API key
• Pricing: Compare API plans

🔗 Related Projects

• countries-states-cities-database — Source database
• countrystatecity NPM — JavaScript/TypeScript packages

---

Made with ❤️ by dr5hn