Python SDK & Packages

pip install countrystatecity-api
export CSC_API_KEY="YOUR_API_KEY"

from countrystatecity import CountryStateCity, CountryStateCityError

try:
    with CountryStateCity() as client:
        states = client.get_states_of_country("IN")
        for state in states[:3]:
            print(state["name"])
except CountryStateCityError as error:
    print(f"Country State City request failed: {error}")

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

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}")

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)

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

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)      # [...]

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")

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")

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)}")

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")

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
pip install --upgrade countrystatecity-regions
pip install --upgrade countrystatecity-postal-codes