Build with AI

Everything an agent or AI builder needs to integrate Ideal Postcodes - agent skills, a CLI, plain-text docs, and per-builder recipes.

Prerequisite: Get an API key

Sign up at ideal-postcodes.co.uk/signup, create an account and get a free API Key to test. Enable automated top-ups to go live.

Want to do a quick test? Use our test, but highly rate limited API Key ak_test. Be sure to change this in production as relying on this will cause your app to break.

Skills

Drop our agent skills into your editor for guided integration of Address Finder, Postcode Lookup, the API, and the CLI. Each skill ships with quickstarts and the gotchas we wish we'd known.

npx skills add ideal-postcodes/skills

Works with Claude Code, Cursor, and Codex out of the box (the package ships matching .claude-plugin, .cursor-plugin, and .codex-plugin manifests).

Source: github.com/ideal-postcodes/skills.

CLI

idpc is built for AI agents and CI: JSON output in non-TTY, stable exit codes, no interactive prompts when piped.

npm install -g @ideal-postcodes/cli
idpc auth login --api-key ak_xxx --user-token ut_xxx
idpc cleanse "10 downing street, london"
idpc find "10 downing" --resolve

The bundled idpc-cli skill (included in npx skills add ideal-postcodes/skills) teaches agents the flag contract.

Full reference: github.com/ideal-postcodes/cli.

llms.txt

A single comprehensive file at docs.ideal-postcodes.co.uk/llms.txt - full API reference, integration guides, code examples, formatted for LLMs. Follows the llms.txt standard.

Paste relevant sections into your model's context, or wire it into a docs MCP server like Context 7.

Markdown docs

Append .md to any docs URL for the plain-text version. Examples:

• /docs/address-finder.md
• /docs/postcode-lookup.md
• /docs/api/find-address.md
• /docs/integrations/woocommerce.md

Useful when you want to feed one specific page into a model rather than the full llms.txt.

AI builder integrations

Use Ideal Postcodes inside browser-based AI app builders. The integration is the same everywhere - install the widget, read the API key from a secret, restrict the key to the deployed origin. Only the secret-storage step differs per builder.

Starter prompt

Paste this into the builder's chat. Replace the secret line with the builder-specific instruction below.

Add UK address autocomplete using Ideal Postcodes.

- Install `@ideal-postcodes/address-finder` and mount it on the
  delivery / billing address fields.
- Reference docs: https://docs.ideal-postcodes.co.uk/docs/address-finder.md
- Read the API key from <BUILDER-SPECIFIC SECRET - see below>.
- After deploying, restrict the key to the deployed origin via Allowed URLs:
  https://docs.ideal-postcodes.co.uk/docs/guides/allowed-urls.md

Builders

• v0 - Add IDEAL_POSTCODES_API_KEY in the project's environment variables (Project Settings → Environment Variables) before sending the prompt.
• Bolt.new - Add the key to the generated .env file as IDEAL_POSTCODES_API_KEY. Bolt's chat picks this up automatically.
• Lovable - Store the key as a Supabase secret (Lovable's recommended pattern for sensitive values). Reference it from the front end via a Supabase Edge Function.
• Replit - Add the key as a Repl Secret named IDEAL_POSTCODES_API_KEY; access via process.env.IDEAL_POSTCODES_API_KEY.
• base44 - Add the key in the project's environment variables panel.
• Leap.new - Add the key as a project secret and pass it into the address-finder constructor.

Coding agents

Tool	Setup
Claude Code	npx skills add ideal-postcodes/skills
Cursor	npx skills add ideal-postcodes/skills (uses bundled .cursor-plugin/)
Codex	npx skills add ideal-postcodes/skills (uses bundled .codex-plugin/)
Windsurf	Add llms.txt as a context source
GitHub Copilot	Reference llms.txt from .github/copilot-instructions.md

shadcn

Drop-in <AddressFinder /> and <PostcodeLookup /> components for shadcn projects - coming soon.

Need help?

• File an issue: github.com/ideal-postcodes/feedback
• Email: support@ideal-postcodes.co.uk