ideal-postcodes-api-integration

Ideal Postcodes API

Direct HTTP integration with the Ideal Postcodes API. Supports multiple client libraries and language SDKs.

Quick Start (fetch)

const key = process.env.IDEAL_POSTCODES_API_KEY;
const response = await fetch(
  'https://api.ideal-postcodes.co.uk/v1/postcodes/SW1A1AA',
  {
    headers: {
      Authorization: `api_key="${key}"`,
    },
  }
);

const data = await response.json();
console.log(data.result); // Array of addresses

Alternatively, pass ?api_key=... in the query string.

Quick Start (axios)

import axios from 'axios';

const client = axios.create({
  baseURL: 'https://api.ideal-postcodes.co.uk/v1',
  headers: {
    Authorization: `api_key="${process.env.IDEAL_POSTCODES_API_KEY}"`,
  },
});

const { data } = await client.get('/postcodes/SW1A1AA');
console.log(data.result);

Core Endpoints

• GET /postcodes/{postcode} — Lookup all addresses for a UK postcode
• GET /autocomplete/addresses — Typeahead address search
• GET /autocomplete/addresses/{address}/gbr — Resolve a UK autocomplete suggestion
• GET /places / GET /places/{place} — Place search and resolve
• POST /cleanse/addresses — Cleanse a freeform address string
• GET /emails, GET /phone_numbers — Email and phone validation

See endpoints/ for the full list (23 operations).

Critical Gotchas

• Auth header format — Authorization: api_key="<your-key>" (with double quotes around the key). Not Bearer, not ApiKey <key>. Query-string ?api_key=... also works
• API key restrictions — default keys are restricted to specific domains. Ensure your domain is in the key's allowed list
• CORS in browsers — the API sets CORS headers for http://localhost in development. Production domains must be explicitly added to your key
• Rate limits — each IP is rate limited at 30 requests per second. Tripping the limit returns a 503
• Error responses — all errors are JSON with a numeric code and human-readable message. Check codes before retrying — see error-codes.md

Reference Layout

• authentication.md — header and query auth, key restrictions
• error-codes.md — error code catalogue with fixes
• endpoints/ — one reference per API operation (parameters, request body, response schema, examples, status codes)
• data/ — one reference per data model (PafAddress, MrAddress, AddressSuggestion, etc.) with field tables and "used by" cross-links

Full Spec

The complete OpenAPI spec is available at:

• npm: @ideal-postcodes/openapi
• web: https://openapi.ideal-postcodes.co.uk/openapi.yaml

Reach for it when you need exhaustive parameter detail beyond what's in the endpoint references.

Full documentation

The full Ideal Postcodes documentation — every guide, API reference, and integration — is available as a single file at llms.txt. Point your agent there for anything this skill doesn't cover.