countrystatecity-regions

Official Python package for region and subregion associations across 250 countries. Part of the countrystatecity ecosystem.

From offline prototype to production

This package provides a versioned offline snapshot. For 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 · API docs · Pricing · Migration guide

Keep API keys in server-side environment variables, never in client-side code or source control.

Installation

pip install countrystatecity-regions

Quick Start

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

# Get all country-region entries
regions = get_all_regions()
# [CountryRegion(countryCode="AF", countryName="Afghanistan", region="Asia", subregion="Southern Asia"), ...]

# Get the region/subregion for a country
us = get_region_by_country("US")
# CountryRegion(countryCode="US", countryName="United States", region="Americas", subregion="Northern America")

# Get all countries in a region
asian_countries = get_countries_by_region("Asia")
# [CountryRegion(countryCode="AF", ...), CountryRegion(countryCode="CN", ...), ...]

# Get all countries in a subregion
south_asia = get_countries_by_subregion("Southern Asia")
# [CountryRegion(countryCode="AF", ...), CountryRegion(countryCode="IN", ...), ...]

# List distinct region/subregion names
regions_list = get_all_region_names()
# ["Africa", "Americas", "Asia", "Europe", "Oceania", "Polar"]

asia_subregions = get_all_subregion_names("Asia")
# ["Central Asia", "Eastern Asia", "South-eastern Asia", "Southern Asia", "Western Asia"]

# Search by country name, code, region, or subregion
results = search_regions("southern asia")

Data Model

class CountryRegion(BaseModel):
    countryCode: str          # ISO2 country code (e.g., "US")
    countryName: str          # Country name (e.g., "United States")
    region: Optional[str]     # Continent/region (e.g., "Americas")
    subregion: Optional[str]  # Geographic subregion (e.g., "Northern America")

API Reference

License

ODbL-1.0 — see LICENSE.

Other Packages in this Ecosystem

Data sourced from countries-states-cities-database.

Made with ❤️ by dr5hn