The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Postio — UK Address, Postcode, Email & Phone Validation listing page.
Postio is the UK validation API for addresses,
emails and phone numbers. This repo holds the JS-family npm packages,
the AI / agent surface, and the cdn.postio.co.uk Worker that powers
Postio's browser drop-in.
First time? Sign up free — first 100 lookups on us, no card needed.
The Postio API + OpenAPI spec live in
postio-uk/postio-api. The
spec is also published as
@postio/openapi.
| Package | What it is |
|---|---|
@postio/api-types | TypeScript types generated from the OpenAPI spec. |
@postio/core | Runtime-agnostic typed client (browser / Node / Workers / Bun / Deno). |
@postio/node | Node SDK on top of core — retries with exponential backoff, structured logger hook. |
@postio/postman-collection | Postman v2.1 collection for every endpoint. |
@postio/address-finder | Browser address autocomplete — ARIA combobox, themable, framework-agnostic source. |
@postio/address-finder-bundled | The same component prebuilt for <script> tag use. |
@postio/react | React hooks + <AddressFinder /> component, TanStack Query under the hood. |
@postio/mcp | Model Context Protocol server — npx -y @postio/mcp for Claude Desktop / Cursor / Windsurf / Zed. |
Each package builds independently (pnpm -F @postio/<name> run build).
The address-finder bundle has a topological-build quirk — use the
... suffix so its workspace dep builds first:
PRs welcome. Conventions:
stage is the working branch; master deploys / publishes via CI.package.json when you intend a release.The full integration index — including the server SDKs in their own repos and the WordPress plugin — lives at postio.co.uk/integrations.
MIT.