Skip to main content

countrystatecity-postal-codes

PyPI Python Version License Type Checked postal-codes postal-codes

Official Python package for postal/ZIP code data — 728,556 postcode/locality records representing 580,593 distinct country/code pairs across 117 countries, plus format metadata for 250 countries and validation regexes for 184. Part of the countrystatecity ecosystem.

Like the countries package, postcode data is lazy-loaded per country — installing the package doesn't load anything into memory until you ask for a specific country's data.

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-postal-codes

Quick Start

from countrystatecity_postal_codes import (
    get_countries_with_postal_data,
    get_postal_info_by_country,
    get_postcodes_of_country,
    get_postcode_by_code,
    get_postcodes_by_code,
    search_postcodes,
    validate_postcode,
)

# Postal code format/regex for a country
us_info = get_postal_info_by_country("US")
# CountryPostalInfo(countryCode="US", postalCodeFormat="#####-####", postalCodeRegex="^\\d{5}(-\\d{4})?$", ...)

# Validate a postcode against the country's known format
validate_postcode("US", "10001")   # True
validate_postcode("US", "abcde")   # False

# All postcodes for a country (lazy loaded)
postcodes = get_postcodes_of_country("AD")
# [Postcode(code="AD100", localityName="Canillo", ...), ...]

# Look up the first entry for a postcode
pc = get_postcode_by_code("AD", "AD100")
print(pc.localityName)  # Canillo

# Get every locality when a postcode is shared
matches = get_postcodes_by_code("BB", "BB18000")
# [Postcode(localityName="Crane", ...), Postcode(localityName="Six Cross Roads", ...)]

# Search by code or locality name within a country
results = search_postcodes("AD", "canillo")

# List postal-format metadata for every country
all_countries = get_countries_with_postal_data()

Data Model

class CountryPostalInfo(BaseModel):
    countryCode: str               # ISO2 country code (e.g., "US")
    countryName: str                # Country name (e.g., "United States")
    postalCodeFormat: Optional[str] # Format pattern (e.g., "#####")
    postalCodeRegex: Optional[str]  # Validation regex (e.g., "^\\d{5}$")
    postcodeCount: int              # Number of individual postcodes available for this country

class Postcode(BaseModel):
    code: str                       # The postal code value (e.g., "10001")
    countryCode: str                # ISO2 country code (e.g., "US")
    stateCode: Optional[str]        # State/province code, if known
    localityName: Optional[str]     # Human-readable place name
    type: Optional[str]             # Granularity: full | outward | sector | district | area
    latitude: Optional[float]
    longitude: Optional[float]

API Reference

Function Description
get_countries_with_postal_data() Get postal format/regex metadata for all countries
get_postal_info_by_country(code) Get postal format/regex metadata for an ISO2 country code
get_postcodes_of_country(code) Get all postcodes for a country (lazy loaded)
get_postcode_by_code(code, postcode) Get the first entry for a postcode within a country
get_postcodes_by_code(code, postcode) Get every entry when a postcode covers multiple localities
search_postcodes(code, query) Search postcodes within a country by code or locality name
validate_postcode(code, postcode) Validate a postcode against the country's known format

Coverage

Individual postcode listings are available for 117 countries with source data upstream: 728,556 postcode/locality records representing 580,593 distinct country/code pairs, with varying granularity per country. get_postal_info_by_country() returns format metadata for all 250 countries and validation regexes for the 184 countries where one is known, even if per-postcode listings aren't available. Check postcodeCount to see how many records are available for a given country.

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-regions Region and subregion associations for 250 countries

Data sourced from countries-states-cities-database.


Made with ❤️ by dr5hn

Metadata

Release files for countrystatecity-postal-codes 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-postal-codes 3.0.1
File Size Uploaded Provenance Actions
countrystatecity_postal_codes-3.0.1.tar.gz 7.9 MB With provenance Details for countrystatecity_postal_codes-3.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for countrystatecity-postal-codes 3.0.1
File Interpreter ABI Platform Actions
countrystatecity_postal_codes-3.0.1-py3-none-any.whl Python 3 none any Details for countrystatecity_postal_codes-3.0.1-py3-none-any.whl

Total release size: 15.8 MB

Release files / countrystatecity_postal_codes-3.0.1.tar.gz

Download URL countrystatecity_postal_codes-3.0.1.tar.gz
Size 7.9 MB
Tags Source
SHA-256 checksum
How to use checksums
f07f1918bdd4b3654d47756f97fc3c0f4f83475471007fb3dd387603b2020a03
BLAKE2b-256 checksum
How to use checksums
d25faf2070304e080cc6bb71ce802f6d4f8e49332a1648cc72ff3ddc64f47cd8
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_postal_codes-3.0.1-py3-none-any.whl

Download URL countrystatecity_postal_codes-3.0.1-py3-none-any.whl
Size 7.9 MB
Tags Python 3
SHA-256 checksum
How to use checksums
3f851b99663059c95d175fd21df5e53ec0e295ffbd4f93ff0b80227f8b633764
BLAKE2b-256 checksum
How to use checksums
8db2486d6ee357de4aa00105d30a8cbf9a01fc4a06853aef4b49dd57dd11ef44
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-postal-codes 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_postal_codes-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