Official Python package for accessing comprehensive countries, states, and cities database with type hints and lazy loading.
- ✅ Type-safe with Pydantic models and mypy support
- ✅ Lazy loading for minimal memory footprint
- ✅ 250+ countries with full metadata
- ✅ 5,000+ states/provinces
- ✅ 151,000+ cities
- ✅ Translations in 18+ languages
- ✅ Timezone data per location
- ✅ Zero external dependencies (except Pydantic)
- ✅ Full test coverage with pytest
pip install countrystatecity-countriesfrom countrystatecity_countries import (
get_countries,
get_country_by_code,
get_states_of_country,
get_cities_of_state,
)
# Get all countries (lightweight)
countries = get_countries()
print(f"Total countries: {len(countries)}")
# Get specific country
usa = get_country_by_code("US")
print(f"Country: {usa.name}")
print(f"Capital: {usa.capital}")
print(f"Currency: {usa.currency_symbol} {usa.currency_name}")
# Get states (lazy loaded)
states = get_states_of_country("US")
print(f"Total states: {len(states)}")
# Get cities (lazy loaded)
cities = get_cities_of_state("US", "CA")
print(f"Cities in California: {len(cities)}")Get all countries with basic metadata.
countries = get_countries()
for country in countries:
print(f"{country.emoji} {country.name} ({country.iso2})")Get country by ISO2 or ISO3 code.
usa = get_country_by_code("US") # or "USA"
print(usa.name) # "United States"Get country by ID.
country = get_country_by_id(1)Search countries by name (case-insensitive).
results = search_countries("united")
# Returns: [United States, United Kingdom, United Arab Emirates]Get countries in a region.
asian_countries = get_countries_by_region("Asia")Get countries in a subregion.
countries = get_countries_by_subregion("Southern Asia")Get all states in a country (lazy loaded).
states = get_states_of_country("US")Get specific state.
california = get_state_by_code("US", "CA")
print(california.name) # "California"Search states within a country.
results = search_states("US", "New")
# Returns: [New York, New Jersey, New Mexico, New Hampshire]Get all cities in a state (lazy loaded).
cities = get_cities_of_state("US", "CA")Get all cities in a country (warning: may return a large list).
cities = get_cities_of_country("US")Search cities.
# Search within a state
results = search_cities("US", "CA", "Los")
# Search entire country
results = search_cities("US", None, "Springfield")class Country(BaseModel):
id: int
name: str
iso2: str
iso3: str
numeric_code: str
phone_code: str
capital: Optional[str]
currency: Optional[str]
currency_name: Optional[str]
currency_symbol: Optional[str]
tld: Optional[str]
native: Optional[str]
region: Optional[str]
subregion: Optional[str]
timezones: List[Dict[str, str]]
translations: Dict[str, str]
latitude: Optional[str]
longitude: Optional[str]
emoji: Optional[str]
emojiU: Optional[str]class State(BaseModel):
id: int
name: str
country_id: int
country_code: str
state_code: str
type: Optional[str]
latitude: Optional[str]
longitude: Optional[str]class City(BaseModel):
id: int
name: str
state_id: int
state_code: str
country_id: int
country_code: str
latitude: str
longitude: str
wikiDataId: Optional[str]from flask import Flask, jsonify
from countrystatecity_countries import get_countries, get_states_of_country
app = Flask(__name__)
@app.route('/api/countries')
def api_countries():
countries = get_countries()
return jsonify([c.dict() for c in countries])
@app.route('/api/countries/<code>/states')
def api_states(code: str):
states = get_states_of_country(code.upper())
return jsonify([s.dict() for s in states])from countrystatecity_countries import get_countries
def get_country_choices():
"""Generate choices for Django ChoiceField."""
countries = get_countries()
return [(c.iso2, c.name) for c in countries]
# In your model
from django.db import models
class UserProfile(models.Model):
country = models.CharField(
max_length=2,
choices=get_country_choices()
)#!/usr/bin/env python3
import sys
from countrystatecity_countries import get_country_by_code, get_states_of_country
def main():
if len(sys.argv) < 2:
print("Usage: python script.py <country_code>")
sys.exit(1)
country_code = sys.argv[1]
country = get_country_by_code(country_code)
if not country:
print(f"Country {country_code} not found")
sys.exit(1)
print(f"\n{country.emoji} {country.name}")
print(f"Capital: {country.capital}")
print(f"Region: {country.region}")
print(f"Currency: {country.currency_symbol} {country.currency_name}")
states = get_states_of_country(country_code)
print(f"\nTotal states/provinces: {len(states)}")
if __name__ == "__main__":
main()The package uses LRU caching and lazy loading for optimal performance:
- Countries list: <50ms load time
- States data: Loaded only when requested
- Cities data: Loaded only when requested
- Memory footprint: <10MB base, grows with usage
# Clone the repository
git clone https://github.com/dr5hn/countrystatecity-pypi.git
cd countrystatecity-pypi/python/packages/countries
# Install dependencies
pip install -e ".[dev]"# Run all tests
pytest
# Run with coverage
pytest --cov=countrystatecity_countries --cov-report=html
# Run specific test file
pytest tests/test_countries.pymypy countrystatecity_countries/# Format code
black countrystatecity_countries/ tests/
isort countrystatecity_countries/ tests/
# Lint code
ruff countrystatecity_countries/ tests/This package is licensed under the Open Database License (ODbL-1.0).
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Run tests (
pytest) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Documentation: GitHub Repository
- Issues: GitHub Issues
- Website: countrystatecity.in
countrystatecity-timezones(Coming soon)countrystatecity-currencies(Coming soon)countrystatecity-languages(Coming soon)countrystatecity-phonecodes(Coming soon)
This package is part of the countries-states-cities-database project.
Made with ❤️ by dr5hn