Metadata-Version: 2.4
Name: countrystatecity-postal-codes
Version: 1.0.0
Summary: Type-safe Python package for postal/ZIP code data — postcodes, localities, and format/validation regex for 100+ countries.
Author-email: dr5hn <support@countrystatecity.in>
Maintainer-email: dr5hn <support@countrystatecity.in>
License: Open Database License (ODbL) v1.0
        
        This package uses data from the countries-states-cities-database project,
        which is licensed under the Open Database License (ODbL) v1.0.
        
        For the full text of the ODbL license, please visit:
        https://opendatacommons.org/licenses/odbl/1-0/
        
        Summary:
        You are free to:
        - Share: Copy and redistribute the database
        - Create: Produce works from the database
        - Adapt: Modify, transform and build upon the database
        
        Under the following conditions:
        - Attribute: You must attribute any public use of the database
        - Share-Alike: If you publicly use any adapted version, you must also offer 
          that adapted database under the ODbL
        - Keep open: If you redistribute the database, you must keep it open
        
Project-URL: Homepage, https://github.com/dr5hn/countrystatecity-pypi
Project-URL: Documentation, https://github.com/dr5hn/countrystatecity-pypi/tree/master/python/packages/postal_codes
Project-URL: Repository, https://github.com/dr5hn/countrystatecity-pypi
Project-URL: Source, https://github.com/dr5hn/countrystatecity-pypi/tree/master/python/packages/postal_codes
Project-URL: Issues, https://github.com/dr5hn/countrystatecity-pypi/issues
Project-URL: Changelog, https://github.com/dr5hn/countrystatecity-pypi/blob/master/python/packages/postal_codes/CHANGELOG.md
Keywords: postal-codes,postcodes,zip-codes,countries,geography,geolocation,validation,lazy-loading,type-hints,pydantic
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic<3.0.0,>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# countrystatecity-postal-codes

[![PyPI](https://img.shields.io/pypi/v/countrystatecity-postal-codes)](https://pypi.org/project/countrystatecity-postal-codes/)
[![Python Version](https://img.shields.io/pypi/pyversions/countrystatecity-postal-codes)](https://pypi.org/project/countrystatecity-postal-codes/)
[![License](https://img.shields.io/badge/License-ODbL--1.0-blue.svg)](LICENSE)
[![Type Checked](https://img.shields.io/badge/type--checked-mypy-blue)](https://mypy.readthedocs.io/)
[![postal-codes](https://static.pepy.tech/personalized-badge/countrystatecity-postal-codes?period=month&units=international_system&left_color=grey&right_color=brightgreen&left_text=postal-codes)](https://pepy.tech/project/countrystatecity-postal-codes)
[![postal-codes](https://static.pepy.tech/personalized-badge/countrystatecity-postal-codes?period=week&units=international_system&left_color=grey&right_color=brightgreen&left_text=postal-codes)](https://pepy.tech/project/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](https://github.com/dr5hn/countrystatecity-pypi) ecosystem.

Like the [countries](https://pypi.org/project/countrystatecity-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

```bash
pip install countrystatecity-postal-codes
```

## Quick Start

```python
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

```python
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)` | Look up a specific postcode within a country |
| `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 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](LICENSE).

## Other Packages in this Ecosystem

| Package | Description |
|---|---|
| [countrystatecity-countries](https://pypi.org/project/countrystatecity-countries/) | 250+ countries, 5,000+ states, 150,000+ cities |
| [countrystatecity-timezones](https://pypi.org/project/countrystatecity-timezones/) | 400+ IANA timezones with country associations and time conversion |
| [countrystatecity-currencies](https://pypi.org/project/countrystatecity-currencies/) | Currency codes, names, and symbols |
| [countrystatecity-translations](https://pypi.org/project/countrystatecity-translations/) | Country name translations in 18+ languages |
| [countrystatecity-phonecodes](https://pypi.org/project/countrystatecity-phonecodes/) | International phone/dialing codes for 250+ countries |
| [countrystatecity-regions](https://pypi.org/project/countrystatecity-regions/) | Continents and geographic subregions for 250+ countries |

Data sourced from [countries-states-cities-database](https://github.com/dr5hn/countries-states-cities-database).

---

Made with ❤️ by [dr5hn](https://github.com/dr5hn)
