> ## Documentation Index > Fetch the complete documentation index at: https://docs.countrystatecity.in/llms.txt > Use this file to discover all available pages before exploring further. # Python Packages > Official countrystatecity Python packages — type-safe, lazily loaded geographical data with Pydantic models and zero extra dependencies The `countrystatecity` Python packages provide access to countries, states, cities, timezones, currencies, and translations 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 | Package | Status | Description | | ------------------------------- | -------- | ------------------------------------------------- | | `countrystatecity-countries` | Released | Countries, states, and cities with lazy loading | | `countrystatecity-timezones` | Released | IANA timezone data and time conversion utilities | | `countrystatecity-currencies` | Released | Currency codes, symbols, and country associations | | `countrystatecity-translations` | Released | Country name translations in 19 languages | | `countrystatecity-phonecodes` | Released | International dialing codes for 250+ countries | ## Installation Install only what you need: ```bash theme={null} pip install countrystatecity-countries pip install countrystatecity-timezones pip install countrystatecity-currencies pip install countrystatecity-translations pip install countrystatecity-phonecodes ``` ## Usage ### Countries ```python theme={null} 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 ```python theme={null} 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 ```python theme={null} 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 ```python theme={null} 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) # [...] ``` ### Timezones ```python theme={null} from countrystatecity_timezones import ( get_all_timezones, get_timezones_by_country, get_timezone_by_zone_name, convert_time, ) # Timezones for a country timezones = get_timezones_by_country("US") print(f"US timezones: {len(timezones)}") # 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 ```python theme={null} 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})") # $ United States Dollar (USD) # All countries using a currency countries = get_countries_by_currency("EUR") print(f"Countries using EUR: {len(countries)}") # Search by name results = search_currencies("dollar") ``` ### Translations ```python theme={null} from countrystatecity_translations import ( get_all_translations, get_translations_by_country, get_translations_by_language, get_translation, ) # Country name in a specific language translation = get_translation("US", "fr") print(translation.translation) # États-Unis # All translations for a country (all 19 languages) translations = get_translations_by_country("IN") # All countries translated into Japanese japanese = get_translations_by_language("ja") print(f"Japanese translations: {len(japanese)}") ``` ### Phone Codes ```python theme={null} 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") # 25 countries use +1 # Works with or without + prefix plus44 = get_countries_by_phonecode("+44") # Search by country name, code, or phone code results = search_phonecodes("united") ``` ## Features Full type hints with Pydantic models and mypy support. Data loads on first access and caches with LRU cache for minimal memory footprint. Only requires Pydantic — no other external packages. 250+ countries, 5,299+ states, 153,765+ cities with coordinates and metadata. ## Data Updates To get the latest data, upgrade any package: ```bash theme={null} pip install --upgrade countrystatecity-countries pip install --upgrade countrystatecity-timezones pip install --upgrade countrystatecity-currencies pip install --upgrade countrystatecity-translations pip install --upgrade countrystatecity-phonecodes ``` ## Source View source, open issues, or contribute. Countries, states, and cities on PyPI. Timezone data on PyPI. Currency data on PyPI. Translations data on PyPI. Phone codes data on PyPI.