{ "openapi": "3.1.0", "info": { "title": "PostCode Check", "version": "0.2.3", "description": "Validate and normalize postal codes offline for 252 countries and territories. By Harlo. 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. No API key today: about 60 requests per minute per IP. 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 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 PostCode Check is not affiliated with, endorsed by or sponsored by Google, the Unicode Consortium, any postal operator, Meta, Anthropic, OpenAI or Anysphere.", "contact": { "name": "Harlo", "email": "digitalpromohub.support@gmail.com" }, "x-plans": [ { "id": "free", "name": "Free", "price_usd_month": 0, "calls_per_month": 2000 }, { "id": "basic", "name": "BASIC", "price_usd_month": 9, "calls_per_month": 50000 }, { "id": "pro", "name": "PRO", "price_usd_month": 29, "calls_per_month": 500000 } ] }, "servers": [ { "url": "https://postcodecheck.mike-tusa.workers.dev" } ], "paths": { "/v1/validate": { "get": { "operationId": "validatePostcode", "summary": "Validate and normalize one postal code", "parameters": [ { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 2 }, "example": "GB" }, { "name": "code", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 32 }, "example": "EC1Y 8SY" } ], "responses": { "200": { "description": "Result (valid true or false)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" } } } }, "400": { "description": "invalid_input or invalid_country", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "string" } } } } } }, "post": { "operationId": "validatePostcodePost", "summary": "Validate one postal code (JSON body)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "country": { "type": "string" }, "code": { "type": "string", "maxLength": 32 } }, "required": [ "country", "code" ] } } } }, "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" } } } }, "400": { "description": "invalid_input or invalid_country", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "string" } } } } } } }, "/v1/countries": { "get": { "operationId": "listCountries", "summary": "List supported countries", "responses": { "200": { "description": "Countries", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "with_postal_codes": { "type": "integer" }, "countries": { "type": "array", "items": { "$ref": "#/components/schemas/Country" } }, "version": { "type": "string" } }, "required": [ "count", "countries" ] } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "string" } } } } } } }, "/v1/batch": { "post": { "operationId": "validateBatch", "summary": "Validate up to 100 postal codes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "country": { "type": "string", "description": "Default country for string items" }, "codes": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "country": { "type": "string" }, "code": { "type": "string" } }, "required": [ "code" ] } ] } } }, "required": [ "codes" ] } } } }, "responses": { "200": { "description": "Results in input order", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "valid_count": { "type": "integer" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Result" } }, "version": { "type": "string" } }, "required": [ "count", "valid_count", "results" ] } } } }, "400": { "description": "invalid_input or invalid_country", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "string" } } } } } } }, "/health": { "get": { "operationId": "health", "summary": "Health", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "version": { "type": "string" } }, "required": [ "ok", "version" ] } } } } } } }, "/mcp": { "post": { "operationId": "mcp", "summary": "Remote MCP endpoint (JSON-RPC 2.0, Streamable HTTP, stateless)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "JSON-RPC response", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Notification accepted" }, "413": { "description": "Body too large" }, "429": { "description": "rate_limited" } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "Optional paid license key (PCCR-…). Omit for anonymous access." }, "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "Country": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "has_postal_codes": { "type": "boolean" }, "format_example": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zip_name": { "type": "string" } }, "required": [ "code", "name", "has_postal_codes", "format_example" ] }, "Result": { "type": "object", "properties": { "valid": { "type": "boolean" }, "normalized": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "format_example": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "type": "string" }, "country_name": { "type": "string" }, "input": { "type": "string" }, "has_postal_codes": { "type": "boolean" }, "zip_name": { "type": "string" }, "reason": { "type": "string", "enum": [ "format_mismatch", "no_postal_codes", "empty" ] }, "message": { "type": "string" }, "version": { "type": "string" } }, "required": [ "valid", "normalized", "format_example", "country", "country_name" ] } } } }