Use PostalCodes.info for postal code API integration patterns: same-origin JSON search, token-protected country exports and canonical HTML lookup pages to validate postal codes, cities, regions and coordinates across 123 countries.
Use live search for autocomplete, country exports for batch validation and canonical HTML pages for human review. These examples use the same public data and URL model as the lookup pages.
curl "https://postalcodes.info/search?q=4%20%C3%81guas&country=PT"
curl "https://postalcodes.info/download.php?country=pt&format=json&t={download_token}"
curl "https://postalcodes.info/postal-codes/portugal/code/1000001"
{
"postal_code": "1000-001",
"place_name": "4 Águas",
"country_code": "PT",
"country": "Portugal",
"admin_name1": "region",
"latitude": null,
"longitude": null
}This page is backed by structured postal records, canonical hierarchy links and representative examples from the current database. The canonical route for this record set is /api.
Start with country exports and same-origin JSON patterns, then use the documented fields as stable import keys.
Use country_code with postal_code, place_name and administrative levels for validation and deduplication.
PostalCodes.info keeps lookup traffic on the canonical domain. The public site exposes crawlable HTML pages for Google and users, while JSON is available through the site search endpoint and through download buttons that mint a same-origin token before exporting CSV, XLSX or JSON.
This avoids a separate API host, keeps canonical signals consolidated on postalcodes.info, and lets developers inspect the same country, prefix and locality pages that power the exported data. A machine-readable OpenAPI document is available at /openapi.json for API directories and integration tooling.
GET https://postalcodes.info/search?q=madrid&country=ES
GET https://postalcodes.info/download.php?country=es&format=json&t={download_token}
GET https://postalcodes.info/postal-codes/portugal/code/1000001
Exported JSON records use stable field names for postal code, place name, country code, administrative levels and WGS84 coordinates. Postal codes must be treated as strings because leading zeroes and spaces are valid in many countries.
Start with high-coverage countries to test search, export and local validation logic before integrating smaller territories.
Cache country exports in your own infrastructure, keep the original postal code string, and use the canonical HTML URL as a human-readable audit trail. If your application only needs interactive lookup, call the search endpoint with a country filter and send users to the canonical result page.
Postal lookup usually has three different jobs: finding a candidate while a user types, validating a stored address, and explaining a result to a human operator. Use the search endpoint for the first job, country exports for the second, and canonical HTML pages for the third. Keeping those jobs separate avoids excessive live requests and gives search engines crawlable pages for the same data.
| Need | Recommended path | Reason |
|---|---|---|
| Autocomplete | /search with country filter | Small responses and direct links to canonical pages. |
| Batch validation | Country JSON or CSV export | One cached download supports many local checks. |
| Manual QA | Country, prefix or code HTML page | Shows hierarchy, related areas and examples. |
| Search discovery | Canonical HTML URLs | Google can crawl the same records users inspect. |
Do not call a live endpoint for every address in a large import. Download the country file, normalize your input strings, and compare country code plus postal code plus locality. When a match is ambiguous, show the operator the canonical page so they can compare administrative levels and coordinates.
For front-end forms, keep validation permissive until the country is known. Many formats are country specific: some are fixed numeric strings, some contain spaces, and some mix letters with digits. The country pages expose the detected format and an example code, so strict rules should be loaded after country selection rather than applied globally.
For analytics and logistics, store coordinates as approximate centroids. They are useful for grouping, routing zones and map previews, but they should not be treated as exact delivery-point coordinates.
No. Current public access is served from postalcodes.info so canonical pages, exports and search results stay on the same host.
Validate locally for batches. Use live search for interactive lookup and canonical pages for human review when a record looks ambiguous.
Cache country exports, prefix pages and code pages. They are public reference data and change much less often than user address input.
Compare the original country, postal code string and locality against the country page, then follow the nearest prefix or code URL for examples.