Skip to main content

countrystatecity-regions

PyPI Python Version License Type Checked regions 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)

Source distribution for countrystatecity-regions 3.0.0
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)

Table of built distributions (wheels) for countrystatecity-regions 3.0.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page