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 through its official Python client:
pip install countrystatecity-api
from countrystatecity import CountryStateCity
csc = CountryStateCity() # reads CSC_API_KEY
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
| Function | Description |
|---|---|
get_all_regions() |
Get all country-region entries |
get_region_by_country(code) |
Get the region/subregion for an ISO2 country code |
get_countries_by_region(region) |
Get all countries in a region (e.g., "Asia") |
get_countries_by_subregion(subregion) |
Get all countries in a subregion (e.g., "Southern Asia") |
get_all_region_names() |
Get all distinct region names, sorted |
get_all_subregion_names(region=None) |
Get all distinct subregion names, optionally filtered by region |
search_regions(query) |
Search by country name, code, region, or subregion |
License
ODbL-1.0 — see LICENSE.
Other Packages in this Ecosystem
| Package | Description |
|---|---|
| countrystatecity-api | Official API client — live data, sync + async, typed |
| countrystatecity-countries | 250 countries, 5,327 states, 156,169 cities |
| countrystatecity-timezones | 432 country/timezone associations with country associations and time conversion |
| countrystatecity-currencies | 249 country/currency associations |
| countrystatecity-translations | 4,724 translations in 19 languages |
| countrystatecity-phonecodes | International phone/dialing codes for 250 countries |
| countrystatecity-postal-codes | Postal/ZIP records for 117 countries |
Data sourced from countries-states-cities-database.
Made with ❤️ by dr5hn
Metadata
Release files for countrystatecity-regions 3.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| countrystatecity_regions-3.0.1.tar.gz | 61.7 kB | With provenance | Details for countrystatecity_regions-3.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| countrystatecity_regions-3.0.1-py3-none-any.whl | Python 3 | none | any | Details for countrystatecity_regions-3.0.1-py3-none-any.whl |
Total release size: 122.2 kB
Release files / countrystatecity_regions-3.0.1.tar.gz
| Download URL | countrystatecity_regions-3.0.1.tar.gz |
|---|---|
| Size | 61.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cec3969f4ed4d63a015a3ebc00e66539eb71c6be3a35b032b376bb3fda14032d
|
|
BLAKE2b-256 checksum How to use checksums |
4576eefd655b32ed77cf5ad157c074c56bb27892ec9774622d91637e84b916c4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.
Transparency logRelease files / countrystatecity_regions-3.0.1-py3-none-any.whl
| Download URL | countrystatecity_regions-3.0.1-py3-none-any.whl |
|---|---|
| Size | 60.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8b949ee8379b48383e4a9c75e82b69c518b6d18a9c27928d0ada2e0c4db7e788
|
|
BLAKE2b-256 checksum How to use checksums |
5daf242a9996f4d7d17abbb6495ed4c3da334eaeabd035d716b37489b258d920
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.
Transparency logSecurity for countrystatecity-regions 3.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for countrystatecity_regions-3.0.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.