A community-maintained repository of postal/ZIP code regex patterns for 50+ countries.
Ideal for form validation, data cleaning, and big data applications.
pip install postal-regexFor development:
git clone https://github.com/ankitgadling/postal-regex.git
cd postal-regex
pip install -e .from postal_regex.core import validate
# Validate by country code
validate("IN", "110001") # True
validate("US", "12345-6789") # True
# By country name
validate("India", "110001") # True
# Invalid returns False
validate("US", "ABCDE") # False- ✅ 50+ countries included, with postal code regex patterns
- ✅ Validate postal codes by country code or country name
- ✅ Normalize country identifiers
from postal_regex.core import normalize
normalize("United States") # "US"
normalize("India") # "IN"- ✅ Works with Pandas and Spark DataFrames
- ✅ JSON schema ensures consistent data structure
- ✅ Precompiled regex for fast Python validation
from postal_regex.core import validate
# Indonesia (ID)
validate("ID", "12345") # **Expected: True** (valid 5-digit code)
validate("Indonesia", "12345") # **Expected: True**
# Bangladesh (BD)
validate("BD", "1205") # **Expected: True** (valid 4-digit code)
# Pakistan (PK)
validate("PK", "44000") # **Expected: True** (valid 5-digit code)
# Sri Lanka (LK)
validate("LK", "00300") # **Expected: True** (valid 5-digit code, e.g., Colombo)
# Nepal (NP)
validate("NP", "44600") # **Expected: True** (valid 5-digit code, e.g., Kathmandu)You can validate postal codes directly from the command line without writing any code.
To validate one or more postal codes for a specific country:
python -m postal_regex.cli validate <postal_code1> <postal_code2> ... <country>Examples:
Validate a single code for India:
python -m postal_regex.cli validate 110001 INOutput:
110001: Valid
Validate multiple codes for the United States:
python -m postal_regex.cli validate 12345 90210 USOutput:
12345: Valid
90210: Valid
You can also use country names:
python -m postal_regex.cli validate 110001 IndiaTo view local validation statistics:
python -m postal_regex.cli statsTo reset statistics:
python -m postal_regex.cli stats --resetValidate postal codes in large datasets with Spark or Pandas.
from pyspark.sql import SparkSession
from postal_regex.bulk import validate_spark_dataframe
spark = SparkSession.builder.getOrCreate()
df = spark.createDataFrame([
{"country": "FR", "postal_code": "75001"},
{"country": "DE", "postal_code": "10115"}
])
df_validated = validate_spark_dataframe(df, country_col="country", postal_col="postal_code")
df_validated.show()import pandas as pd
from postal_regex.bulk import validate_dataframe
df = pd.DataFrame({
"country": ["FR", "DE"],
"postal_code": ["75001", "10115"]
})
df_validated = validate_dataframe(df, country_col="country", postal_col="postal_code")
print(df_validated)We ❤️ contributions! Help expand coverage or improve docs.
- Fork the repo and create a feature branch:
git checkout -b feat/new-country. - Add/update patterns in
postal_regex/data/(follow JSON schema). - Run tests:
pytest. - Commit and push:
git commit -m "Add postal patterns for [Country]". - Open a Pull Request—reference any related issue.
See CONTRIBUTING.md for detailed guidelines, including testing new patterns and updating examples.
MIT License. See LICENSE for details.
⭐ Star this repo if it's useful! Found a bug or missing country? Open an issue. Questions? Join the discussion!