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,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)

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

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

Release 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 log

Security 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.

Select from 2 files

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 log

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