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,308 states, 171,938 cities |
| countrystatecity-timezones | 432 IANA timezones 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 116 countries |
Data sourced from countries-states-cities-database.
Made with ❤️ by dr5hn
Metadata
Release files for countrystatecity-regions 3.0.0
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.0.tar.gz | 37.7 kB | Without provenance | Details for countrystatecity_regions-3.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| countrystatecity_regions-3.0.0-py3-none-any.whl | Python 3 | none | any | Details for countrystatecity_regions-3.0.0-py3-none-any.whl |
Total release size: 75.5 kB
Release files / countrystatecity_regions-3.0.0.tar.gz
| Download URL | countrystatecity_regions-3.0.0.tar.gz |
|---|---|
| Size | 37.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3d13812cbabaeb78528b004c074dba1ae302838c59381970a7830f534c056e82
|
|
BLAKE2b-256 checksum How to use checksums |
b6349dbb7db798355e83d1ef858b0cf6bd89597787a727f4b42e6f7ac6164cef
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.15.1
|
Release files / countrystatecity_regions-3.0.0-py3-none-any.whl
| Download URL | countrystatecity_regions-3.0.0-py3-none-any.whl |
|---|---|
| Size | 37.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ca648b2b23b81d6c8db68c6c1e0aec26f0bb9cdb1a9f8e81628a79e91e588618
|
|
BLAKE2b-256 checksum How to use checksums |
b15deaba8012497b52964c01c9e3704901d4d282404405f45b8bab65cb8ce1e8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.15.1
|
Security for countrystatecity-regions 3.0.0
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A 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.