> ## Documentation Index
> Fetch the complete documentation index at: https://docs.countrystatecity.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Postcodes

> 844,248 postal codes across 125 countries with type classification, source tracking, and query examples

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

## Coverage

| Stat              | Value                               |
| ----------------- | ----------------------------------- |
| Total postcodes   | 844,248                             |
| Countries covered | 125                                 |
| Granularity types | 4 (full, outward, sector, district) |

## Postcode Types

| Type       | Description                                                           | Example                     |
| ---------- | --------------------------------------------------------------------- | --------------------------- |
| `full`     | Complete postcode identifying a specific delivery point or small area | `90210` (US), `110001` (IN) |
| `outward`  | First part of a UK-style postcode identifying the postal district     | `SW1A`                      |
| `sector`   | Intermediate granularity within a district                            | `SW1A 1`                    |
| `district` | Broadest level, covering an entire postal district                    | `SW1`                       |

## Query Examples

### Look up postcodes for a country

<CodeGroup>
  ```sql MySQL / PostgreSQL theme={null}
  SELECT postcode, locality_name, type
  FROM postcodes
  WHERE country_code = 'IN'
  ORDER BY postcode
  LIMIT 20;
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.countrystatecity.in/v1/countries/IN/postcodes', {
    headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' }
  });
  const postcodes = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
    'https://api.countrystatecity.in/v1/countries/IN/postcodes',
    headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
  )
  postcodes = response.json()
  ```
</CodeGroup>

### Validate a postcode format

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

```sql theme={null}
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

```sql theme={null}
SELECT postcode, country_code, type, locality_name
FROM postcodes
WHERE country_code = 'GB'
  AND locality_name ILIKE '%London%'
ORDER BY type, postcode;
```

### Count postcodes per country

```sql theme={null}
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) and the JSON export. It is **not** included in the CSV, YAML, or GeoJSON exports by default.

<Tip>
  Use the [Export Tool](https://export.countrystatecity.in) to download a postcodes-only dataset for specific countries, which is significantly smaller than the full dump.
</Tip>

## Related

<CardGroup cols={2}>
  <Card title="Database Schema" icon="sitemap" href="/database/schema">
    Full table definitions including the postcodes table structure.
  </Card>

  <Card title="Export Tool" icon="download" href="/tools/export-tool">
    Export postcodes data in your preferred format.
  </Card>
</CardGroup>