countrystatecity-postal-codes

Official Python package for postal/ZIP code data — 844,248 postcode/locality records representing 672,370 distinct codes across 125 countries, plus format metadata for 250 countries and validation regexes for 189. 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.

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

Coverage

Individual postcode listings are available for 125 countries with source data upstream: 844,248 postcode/locality records representing 672,370 distinct codes, with varying granularity per country. get_postal_info_by_country() returns format metadata for all 250 countries and validation regexes for the 189 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

Data sourced from countries-states-cities-database.

Made with ❤️ by dr5hn