Postcodes.io vs Ideal Postcodes: which UK address lookup should you use?

The names make these services sound interchangeable. They are not. The choice is a data-modelling decision with consequences for conversion, fulfilment and support. Asking “which postcode API is cheaper?” skips the more important question: does this step need a postcode record or an address record?

Postcodes.io and Ideal Postcodes return different kinds of record

Postcodes.io answers “where is this postcode?”

Postcodes.io describes itself as a free UK postcode lookup API and geocoder. Its open-source service exposes postcode lookup, autocomplete, bulk lookup, reverse geocoding, nearest-postcode search and terminated-postcode search. The underlying service publishes the ONS Postcode Directory, Ordnance Survey Open Names and Scottish Postcode Directory datasets. Postcodes.io API documentation Postcodes.io source and data overview

A result can include a normalised postcode, latitude and longitude, country, region, local authority, parliamentary constituency, statistical areas and their codes. That is excellent for territory checks, routing, analytics, public-data joins and answering “is this postcode in an area we serve?”

The Office for National Statistics explains another subtle limitation: ONS postcode directories contain current and terminated postcodes, and postcode geography does not always follow administrative boundaries. ONSPD assigns a postcode according to the administrative area containing its geographical centre. ONS guidance on postcode directories and boundaries

Ideal Postcodes answers “which deliverable address did the user mean?”

Ideal Postcodes provides authenticated address search, postcode lookup and address cleansing. A postcode lookup returns the structured addresses at that postcode; its two-step Address Search finds candidates from partial text and resolves the selected candidate to a full record. The service identifies Royal Mail PAF as a core UK address source and says it is updated daily. Ideal Postcodes API reference Ideal Postcodes OpenAPI overview

Its integration guidance treats three address lines, post town and postcode as the minimum fields for a complete deliverable UK address. Results can also include address components and identifiers such as a UPRN, depending on the enabled dataset. Ideal Postcodes postcode-lookup configuration

This is a metered service: keys have balances, restrictions and usage history. The current API reference documents a default per-IP rate limit of 30 requests per second, with a separate limit for autocomplete. Treat both commercial terms and operational limits as deployment configuration, not constants buried in application code. The same API reference documents key-based authentication and appropriate HTTP errors.

Postcodes.io vs Ideal Postcodes: side-by-side

Postcodes.io source code is MIT-licensed and Great Britain postcode data is available under the OS OpenData licence. Its licence page says commercial use of Northern Ireland postcode data requires a licence from Land & Property Services. Check the current terms for the dataset and use case you deploy; “the HTTP endpoint is free” does not remove downstream data obligations. Postcodes.io licence summary

The real project boundary: postcode lookup inside a UK cover funnel

Appycodes has built and run the website conversion system for PlusHeat, a UK boiler and home-emergency cover business, since 2021. The documented production flow combines a three-axis plan configurator, postcode address lookup, a live plan summary, agreement start date, marketing preferences, CRM synchronisation and lead-source attribution. See the PlusHeat case study.

The difficult boundary is easy to miss: a valid postcode is not enough for a premises-based customer journey. The sales or operations team needs the address the customer selected, while service-area logic may need only the postcode and its geography. Collapsing both into one “address lookup” step either leaves the CRM without a complete address or makes every eligibility check depend on a paid premises lookup.

The Appycodes Premises Dependency Score

We use a simple ten-point model to stop teams buying an address service for a geography problem—or shipping a postcode API where operations need a real premises. Score the step where the address is captured, not the product as a whole.

The score is a decision aid, not an accreditation. A warehouse territory heatmap is normally 0–2. A retailer shipping parcels is usually 8–10. A home-services lead form may split: 2 for the early “do we cover your area?” step, then 9 when the customer chooses the address that operations will use. Splitting those stages is often the cleanest architecture and the best conversion experience.

A provider boundary that survives pricing and API changes

Keep provider response shapes out of your checkout, onboarding or CRM model. Return a narrow internal contract instead. That makes it possible to change provider, add a fallback, or move an API key server-side without rewriting every form.

import { NextRequest, NextResponse } from "next/server";

const compact = (value: string) =>
  value.trim().toUpperCase().split(" ").join("");

export async function GET(request: NextRequest) {
  const postcode = compact(
    request.nextUrl.searchParams.get("postcode") ?? ""
  );
  const mode = request.nextUrl.searchParams.get("mode");

  if (!/^[A-Z0-9]{5,7}$/.test(postcode)) {
    return NextResponse.json(
      { error: "Enter a full UK postcode" },
      { status: 400 }
    );
  }

  if (mode === "geography") {
    const response = await fetch(
      `https://api.postcodes.io/postcodes/${postcode}`,
      { next: { revalidate: 86400 } }
    );
    if (!response.ok) {
      return NextResponse.json({ error: "Postcode not found" }, { status: 404 });
    }
    const { result } = await response.json();
    return NextResponse.json({
      postcode: result.postcode,
      latitude: result.latitude,
      longitude: result.longitude,
      region: result.region,
      localAuthorityCode: result.codes.admin_district,
    });
  }

  if (mode === "address") {
    const key = process.env.IDEAL_POSTCODES_API_KEY;
    if (!key) throw new Error("IDEAL_POSTCODES_API_KEY is missing");
    const url = new URL(
      `https://api.ideal-postcodes.co.uk/v1/postcodes/${postcode}`
    );
    url.searchParams.set("api_key", key);
    const response = await fetch(url, { cache: "no-store" });
    if (!response.ok) {
      return NextResponse.json({ error: "Address lookup failed" }, { status: 502 });
    }
    const { result } = await response.json();
    return NextResponse.json({
      addresses: result.map((address: Record<string, string>) => ({
        line1: address.line_1,
        line2: address.line_2,
        line3: address.line_3,
        postTown: address.post_town,
        postcode: address.postcode,
        uprn: address.uprn,
      })),
    });
  }

  return NextResponse.json({ error: "Choose geography or address" }, { status: 400 });
}

The format check above is only an early guard. A regular expression cannot prove that a postcode is allocated; the provider lookup makes that decision. In production, add an abort timeout, structured error codes, request correlation, quota alerts and tests for malformed, terminated and unavailable results. Cache postcode geography aggressively enough for your freshness requirement. Cache or retain provider address data only where the contract and data licence permit it.

The failure paths belong in the user journey

GOV.UK’s address pattern recommends accepting postcodes with different case, spacing and common punctuation, and providing a manual option for international, missing or incorrectly listed addresses. It also notes that county is not required for a correct UK postal address. These are small details with outsized effects on form completion. GOV.UK Design System address pattern

Recommendations for UK retailers, SaaS teams and field-service businesses

What Appycodes recommends after real implementations

Begin with the output contract. If the next step needs only a postcode, coordinates or administrative code, use Postcodes.io. If a person or parcel must arrive at a door, use premises-level address data. Where the journey has both needs, keep them as separate calls with separate caching, cost and failure policies.

Whichever provider you choose, accept messy human input, offer manual entry, keep secrets and quotas controlled, store confirmation separately from enrichment, and observe the failure rate. A good address integration is not the one that always shows a dropdown; it is the one that still completes the business process when no dropdown can be shown.

This article provides technical and operational guidance, not legal or licensing advice. Confirm address data licensing, retention and regulated-product requirements for your organisation and deployment.