Postcodes

The postcodes table contains 844,248 records covering 125 countries. Each record includes the postcode / ZIP code string, country, granularity type, source attribution, and locality name.

This is informational postcode data, not an address verification or mail-deliverability service. A record confirms a code exists in the dataset — it does not confirm a delivery point, standardize an address, or guarantee mail will arrive.

Coverage

Stat	Value
Total postcodes	844,248
Countries covered	125
Distinct `type` values in the current dataset	5 (`full`, `area`, `fsa`, `po_box`, `street`)

type is a source-provided classification, not a fixed enum on either the database column or the API. It reflects whatever granularity each country’s source data actually distinguishes, and can gain new values as more sources are imported — don’t hardcode a switch over a closed list.

Postcode Types

The five values present in the current dataset, most to least common:

Type	Description	Countries	Example
`full`	Complete postcode identifying a specific delivery point or small area — the default for most countries	113, e.g. Portugal, Mexico, Japan, US, Malta	`90210` (US)
`area`	A broader geographic area code, used where the source data doesn’t resolve to a specific delivery point	11, e.g. Netherlands, Iran, UK, Isle of Man, Bermuda	`98714` (French Polynesia)
`fsa`	Forward Sortation Area — the first 3 characters of a Canadian postal code, identifying a wide geographic area	Canada only	`A0A`
`po_box`	Postal delivery via PO Box, distinct from a street-delivery code for the same area	South Africa only	`0001` (Pretoria)
`street`	Street/physical-delivery code, distinct from a PO Box code for the same area	South Africa only	`0002` (Pretoria)

Query Examples

Look up postcodes for a country

SELECT code, locality_name, type
FROM postcodes
WHERE country_code = 'IN'
ORDER BY code
LIMIT 20;

const response = await fetch('https://api.countrystatecity.in/v1/countries/IN/postcodes?limit=20', {
  headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' }
});
const page = await response.json();
console.log(page.data);          // array of postcode records
console.log(page.pagination);    // { limit, next_cursor, has_more }

import requests

response = requests.get(
  'https://api.countrystatecity.in/v1/countries/IN/postcodes',
  params={'limit': 20},
  headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)
page = response.json()
postcodes = page['data']

This listing endpoint requires a Supporter+ plan — including a bare request with no ?q= at all, to stop lower-tier keys from scraping the full dataset. See Get Postcodes by Country for full query parameters, pagination, and tier-based field availability. For a single known code, Get Postcode by Code is free on every plan.

Validate a postcode format

Use the postal_code_regex field on the countries table to validate a postcode before querying:

SELECT c.name, c.postal_code_format, c.postal_code_regex
FROM countries c
WHERE c.iso2 = 'GB';
-- postal_code_format: "@# #@@" or "@## #@@" etc.
-- postal_code_regex:  GIR[ ]?0AA|...

Find postcodes by locality

SELECT code, country_code, type, locality_name
FROM postcodes
WHERE country_code = 'GB'
  AND locality_name ILIKE '%London%'
ORDER BY type, code;

Count postcodes per country

SELECT country_code, COUNT(*) AS total, COUNT(DISTINCT type) AS types
FROM postcodes
GROUP BY country_code
ORDER BY total DESC
LIMIT 10;

Availability by Format

The postcodes table is included in all SQL-based exports (MySQL, PostgreSQL, SQLite, SQL Server), the JSON export, and the CSV and YAML exports. It is not included in the GeoJSON export.

Use the Export Tool to download a postcodes-only dataset for specific countries, which is significantly smaller than the full dump.

Get Postcode by Code

Exact lookup via the hosted API, free on every plan.

Get Postcodes by Country

Paginated listing and search via the hosted API. Requires Supporter+.

Database Schema

Full table definitions including the postcodes table structure.

Export Tool

Export postcodes data in your preferred format.

Database Documentation

Installation Guides

Support

Coverage

Postcode Types

Query Examples

Look up postcodes for a country

Validate a postcode format

Find postcodes by locality

Count postcodes per country

Availability by Format

Get Postcode by Code

Get Postcodes by Country

Database Schema

Export Tool

​Coverage

​Postcode Types

​Query Examples

​Look up postcodes for a country

​Validate a postcode format

​Find postcodes by locality

​Count postcodes per country

​Availability by Format

​Related

Get Postcode by Code

Get Postcodes by Country

Database Schema

Export Tool

Coverage

Postcode Types

Query Examples

Look up postcodes for a country

Validate a postcode format

Find postcodes by locality

Count postcodes per country

Availability by Format

Related