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 — 725,993 postcode/locality records representing 578,033 distinct codes across 116 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 116 countries with source data upstream: 725,993 postcode/locality records representing 578,033 distinct codes, 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,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-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.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-postal-codes 3.0.0
File Size Uploaded Provenance Actions
countrystatecity_postal_codes-3.0.0.tar.gz 7.8 MB Without provenance Details for countrystatecity_postal_codes-3.0.0.tar.gz

Built distribution (wheel)

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

Total release size: 15.6 MB

Release files / countrystatecity_postal_codes-3.0.0.tar.gz

Download URL countrystatecity_postal_codes-3.0.0.tar.gz
Size 7.8 MB
Tags Source
SHA-256 checksum
How to use checksums
21f05ed9e49e9bf366e2b356aa4583e09df8ac67cf423ddf308bd394041a5806
BLAKE2b-256 checksum
How to use checksums
2825687b66bbab8e56e037fa4a9d53e859ccedd38a122ff96aa472789430886f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.1

Release files / countrystatecity_postal_codes-3.0.0-py3-none-any.whl

Download URL countrystatecity_postal_codes-3.0.0-py3-none-any.whl
Size 7.8 MB
Tags Python 3
SHA-256 checksum
How to use checksums
b63e8681424b66a733b577646c96f3da0a2b0b8bd894029c7fb89ad44a05fe24
BLAKE2b-256 checksum
How to use checksums
39e15a2c14439228b5ca70ff2cec41b95b63e4a3edcaafa73482be90ca696e84
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.1

Security for countrystatecity-postal-codes 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