countrystatecity-postal-codes

Official Python package for postal/ZIP code data — 844,000+ postcodes with localities and coordinates across 125 countries, plus format/validation regex for all 250+ countries. 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.

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,
    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}$", ...)

# 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 a specific postcode
pc = get_postcode_by_code("AD", "AD100")
print(pc.localityName)  # Canillo

# 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 postcodes total, varying granularity per country). get_postal_info_by_country() returns format/regex metadata for all 250+ countries where known, even if per-postcode listings aren't available — check postcodeCount to see how many individual postcodes 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