# PostCode Check by Harlo

> Validate and normalize postal codes offline for 252 countries and territories (182 use postal codes). JSON API, batch endpoint and a remote MCP server for AI agents. This is a format check: valid means the code has the right shape for the country. It does not confirm that the code is assigned, exists or is deliverable.

## For AI agents

- [MCP server](https://postcodecheck.mike-tusa.workers.dev/mcp): remote MCP over Streamable HTTP (POST only, stateless, JSON responses). Protocol versions: 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05. Tools: `validate_postcode`, `list_countries`. All read-only. Client config: `{"mcpServers":{"postcodecheck":{"type":"http","url":"https://postcodecheck.mike-tusa.workers.dev/mcp"}}}`
- [OpenAPI 3.1 spec](https://postcodecheck.mike-tusa.workers.dev/openapi.json)
- [MCP server card](https://postcodecheck.mike-tusa.workers.dev/.well-known/mcp/server-card.json)
- Works with AI agents and assistants that can call an MCP server or a JSON API, for example Muse, Claude, ChatGPT or Cursor (descriptive only). PostCode Check is not affiliated with, endorsed by or sponsored by Google, the Unicode Consortium, any postal operator, Meta, Anthropic, OpenAI or Anysphere.

## JSON API

- `GET https://postcodecheck.mike-tusa.workers.dev/v1/validate?country=GB&code=ec1y8sy` (or POST JSON {"country","code"}): { valid, normalized, format_example, country, country_name, input, has_postal_codes, zip_name?, reason?, message?, version }. Invalid formats return 200 with valid false and reason format_mismatch | no_postal_codes | empty.
- `GET https://postcodecheck.mike-tusa.workers.dev/v1/countries`: { count, with_postal_codes, countries [ { code, name, has_postal_codes, format_example, zip_name? } ] }.
- `POST https://postcodecheck.mike-tusa.workers.dev/v1/batch` JSON { "country": "US", "codes": ["95014", {"country":"CA","code":"h3z2y7"}] }: up to 100 codes; { count, valid_count, results[] }.
- `GET https://postcodecheck.mike-tusa.workers.dev/health`: { ok, version }.
- country: ISO 3166-1 alpha-2, case-insensitive (UK → GB). code: max 32 characters. POST bodies max 32768 bytes (413 above).
- Errors: { "error": { "code", "message", "field"? } } with 400 invalid_input / invalid_country, 404 not_found, 405 method_not_allowed, 413 payload_too_large, 429 rate_limited (Retry-After).

## Limits and pricing

- No API key and no sign-up today: about 60 requests per minute per IP across /v1 and MCP tools/call (a batch is one request here). Non-check MCP messages are capped at about 120/min per IP; MCP bodies max 32768 bytes.
- Plans (a batch counts one call per code): Free $0/mo · 2,000 calls/mo; BASIC $9/mo · 50,000 calls/mo; PRO $29/mo · 500,000 calls/mo. No key: free and anonymous with a per-minute limit per IP. BASIC license keys (PCCR-…) go in Authorization: Bearer <key> or X-API-Key. Get BASIC: https://buy.polar.sh/polar_cl_vxapQmele1ma7rDI0te4mqOof1nuv3slVMVEh0zKs7Y PRO license keys (PCCP-…) work the same way. Get PRO: https://buy.polar.sh/polar_cl_tgmmwAqsFpnS3lq9bDcz1nFdOnfwcKuY8x2D12T1yc5
- Postal codes you submit are processed in memory and discarded when the response is sent. They are never written to storage, logs or analytics, and PostCode Check makes no network requests.
- Data: Google libaddressinput address metadata (Apache-2.0), snapshot 2026-10-26; country names from Unicode CLDR.

## Optional

- [Privacy](https://postcodecheck.mike-tusa.workers.dev/privacy)
- [Terms](https://postcodecheck.mike-tusa.workers.dev/terms)
- Contact: digitalpromohub.support@gmail.com