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

One postcode, two different records

Postcodes.io is a free UK postcode lookup API and geocoder, maintained as an open-source project by Ideal Postcodes. It serves the ONS Postcode Directory, Ordnance Survey Open Names and Scottish Postcode Directory, and exposes lookup, autocomplete, bulk lookup, reverse geocoding and terminated-postcode search. A result carries coordinates, country, region, local authority, constituency and statistical codes. That is exactly what territory checks, routing, analytics and public-data joins need. Postcodes.io API docs

Ideal Postcodes is an authenticated, metered service over Royal Mail PAF and other datasets. A postcode lookup returns the structured addresses at that postcode; its two-step address search finds candidates from partial text and resolves the selected one to a full record, with UPRNs where the dataset allows. Three address lines, post town and postcode are the minimum for a deliverable UK address. The default rate limit is 30 requests per second per IP, with a separate limit for autocomplete. Ideal Postcodes API reference

Side by side

Postcodes.io code is MIT-licensed and Great Britain data is under the OS OpenData licence. Commercial use of Northern Ireland postcode data requires a licence from Land & Property Services. A free endpoint does not remove downstream data obligations. Postcodes.io licences

A real boundary: a cover funnel for a top UK home cover provider

Since 2021 we have built and run the website that sells boiler and home-emergency cover for a top UK home cover provider: a plan configurator, a lead form with postcode lookup, a live plan summary, agreement start date, marketing preferences and CRM sync. This is the live lookup step.

The boundary is easy to miss. A valid postcode is not enough for a premises-based customer journey. The operations team needs the address the customer selected, while the service-area rule needs only the postcode. Collapse both into one “address lookup” step and you either leave the CRM without a complete address or make every eligibility check depend on a paid premises lookup.

What our production record actually shows

A comparison should say what its author runs. Across our UK client work since 2021, premises-level lookups in production run on Loqate: the Capture Find and Retrieve endpoints on WordPress and WooCommerce checkouts, and the Verify endpoint behind a Node parcel-quoting backend that needs international coverage. Google Places covers two enquiry forms. One survey quote wizard uses a free-tier UK lookup with a daily cap. We have not shipped Postcodes.io or Ideal Postcodes to production.

The one Postcodes.io evaluation, in September 2026, was rejected within a day. A quote wizard captured a postcode and a property value to price a survey, then showed the job address as “to be confirmed”, because a postcode is not a premises. Postcodes.io could not return the list of properties the surveyor needed, so the team moved to a premises-level provider. That is the dependency score in one sentence: the eligibility step scored 2, the booking step scored 9, and the tool chosen for the first could not do the second.

Two more findings changed how we quote lookups. Cost is a subscription, and it shapes the design: on one commercial provider the Find call with a postcode filter validates without consuming a paid lookup, while Retrieve is charged, so validation can be free and premises resolution paid for only at the point of need. And provider validation is not carrier validation: a parcel-quoting client saw postcodes the address provider accepted and a courier’s rates API rejected. Shipping products must validate against the carrier that will deliver.

The Premises Dependency Score

A 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.

A warehouse territory heatmap is 0–2. A retailer shipping parcels is 8–10. A home-services lead form splits: 2 for “do we cover your area?”, then 9 when the customer chooses the address operations will use. Splitting those stages is usually 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 and CRM model. Return a narrow internal contract. That makes it possible to change provider, add a fallback or move a 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 res = await fetch(`https://api.postcodes.io/postcodes/${postcode}`, {
      next: { revalidate: 86400 },
    });
    if (!res.ok) return NextResponse.json({ error: "Postcode not found" }, { status: 404 });
    const { result } = await res.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 res = await fetch(url, { cache: "no-store" });
    if (!res.ok) return NextResponse.json({ error: "Address lookup failed" }, { status: 502 });
    const { result } = await res.json();
    return NextResponse.json({
      addresses: result.map((a: Record<string, string>) => ({
        line1: a.line_1, line2: a.line_2, line3: a.line_3,
        postTown: a.post_town, postcode: a.postcode, uprn: a.uprn,
      })),
    });
  }

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

1. The regex is only an early guard. It cannot prove a postcode is allocated; the provider lookup decides. Add an abort timeout, structured error codes and quota alerts.
2. Valid postcode, no address returned. Offer manual entry immediately and record the lookup outcome, not a fabricated match.
3. New builds and converted flats go missing. Let the user enter and confirm; store provenance as “manual”.
4. Follow the GOV.UK address pattern. Accept any case and spacing, do not require county, and keep a manual route for international or unlisted addresses. GOV.UK Design System

Recommendations by business type

Primary sources

• Postcodes.io API documentation
• Postcodes.io source and data overview
• Postcodes.io licence summary
• Ideal Postcodes API reference
• Ideal Postcodes OpenAPI overview
• Ideal Postcodes postcode-lookup configuration
• ONS guidance on postcode directories
• GOV.UK Design System address pattern

Technical and operational guidance, not legal or licensing advice. Confirm data licensing and retention for your deployment.