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.1.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.1.0
File Size Uploaded Provenance Actions
countrystatecity_regions-3.1.0.tar.gz 61.9 kB With provenance Details for countrystatecity_regions-3.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for countrystatecity-regions 3.1.0
File Interpreter ABI Platform Actions
countrystatecity_regions-3.1.0-py3-none-any.whl Python 3 none any Details for countrystatecity_regions-3.1.0-py3-none-any.whl

Total release size: 122.4 kB

Release files / countrystatecity_regions-3.1.0.tar.gz

Download URL countrystatecity_regions-3.1.0.tar.gz
Size 61.9 kB
Tags Source
SHA-256 checksum
How to use checksums
6479d09fb7a339dd5c14430a387040d520d54d9cc98b9a5116caec5c86a4330e
BLAKE2b-256 checksum
How to use checksums
afef897fcacce9cb5a69fac79ccb7b041bebc8ab43af124638d5029d9a73d5ff
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.1.0-py3-none-any.whl

Download URL countrystatecity_regions-3.1.0-py3-none-any.whl
Size 60.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4eeb656dac8b2d2819abe09d5b41c98a471f76a69917f2aca57637e894aad23b
BLAKE2b-256 checksum
How to use checksums
c0895fd045df71d1e907abe0248678a2886f77f0490ee3489fde191242018421
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.1.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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for countrystatecity_regions-3.1.0.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