Developer Portal

Bulk Access & Integration Endpoints

File-based downloads (CSV/XLSX/JSON) plus lightweight JSON routes used by the site for lookups and previews.

File Access (Available Today)

For large-scale use, the recommended integration is downloadable files (CSV/XLSX/JSON) per territory. This matches the public registry and avoids brittle scraping patterns.

// Download a country dataset (example)

GET https://postalcodes.info/download.php?country=es&format=csv&t={token}

Downloads require a short-lived token (to protect the endpoint from abusive automation). The token is embedded on any HTML page and is also used by the download buttons.

// Curl quick-start (copy/paste)

TOKEN=$(curl -s https://postalcodes.info/datasets | python3 -c "import re,sys; m=re.search(r"window\\.dl_config\\s*=\\s*\\{\\s*t:\\s*'([^']+)'\\s*\\}", sys.stdin.read()); print(m.group(1) if m else '')")
curl -L -o Spain-Postal-Codes.csv "https://postalcodes.info/download.php?country=es&format=csv&t=$TOKEN"

// Lookup suggestions endpoint used by the UI

GET https://postalcodes.info/search?q={query}&country={iso2}

Key Features

🔹 Download files: Country datasets in CSV/XLSX/JSON.
🔹 Lookup endpoint: Lightweight JSON responses for UI suggestions.
🔹 Structured hierarchy: ISO codes + admin levels + coordinates.
🔹 Clear licensing: ODbL 1.0 for datasets with attribution guidance.

Interactive API (Preview)

For interactive lookups, use the public JSON routes on this domain (for example, /search). For heavy workloads, prefer territory downloads instead of crawling HTML pages.

Read Full API Docs

Integration Standards

Postalcodes.info returns structured JSON for interactive routes on this domain (for example, search) and provides downloadable files for system-to-system integration.

Fair use: Automated access may be throttled or blocked under abusive patterns. For bulk workloads, prefer dataset downloads instead of crawling HTML pages.

Common Use Cases

Teams use Postalcodes datasets and routes to normalize user input, enrich CRM or logistics records with standardized locality metadata, and power geospatial analysis. It is also useful for RAG pipelines and machine learning features that need consistent administrative hierarchies across territories.

If you maintain a multi-region platform, the datasets and routes provide a single schema for address codes, place names, admin levels, and coordinates. That consistency is especially useful for aggregations, deduplication, and audit trails when multiple providers disagree.

Response Schema Highlights

Interactive routes on this domain are designed for lightweight lookups (for example, search suggestions). Download files contain normalized locality fields (address codes, place names, administrative levels) and WGS84 coordinates as approximate administrative centroids.

For best performance, we recommend caching responses by cc and postal_code and using incremental refreshes for bulk jobs.

Data Freshness & Provenance

Datasets are built from official postal operators, national statistics offices, and verified open registries. We track update cadence per territory and keep provenance metadata to help teams comply with licensing and attribution requirements.

If you need guaranteed update windows or custom feeds, the documentation page outlines supported export formats and data delivery options.