Address API documentation

curl "https://autopostcode.com/api/public/lookup?postcode=SW1A%201AA" \
  -H "x-api-key: ap_live_xxxxxxxxxxxxxxxx"

// Postcode Lookup — return every address on a full UK postcode.
const API_KEY = "ap_live_xxxxxxxxxxxxxxxx";

async function lookupPostcode(postcode) {
  const res = await fetch(
    "https://autopostcode.com/api/public/lookup?postcode=" +
      encodeURIComponent(postcode),
    { headers: { "x-api-key": API_KEY } }
  );
  if (!res.ok) throw new Error("Lookup failed: " + res.status);
  return res.json(); // Array of address objects
}

lookupPostcode("SW1A 1AA").then(console.log);

[
  {
    "postcode": "SW1A 1AA",
    "line1": "Buckingham Palace",
    "line2": "",
    "line3": "",
    "town": "London",
    "county": "Greater London",
    "country": "United Kingdom"
  }
]

curl "https://autopostcode.com/api/public/autocomplete?q=10%20downing" \
  -H "x-api-key: ap_live_xxxxxxxxxxxxxxxx"

// Address Autocomplete — Fetchify-style search-as-you-type.
const API_KEY = "ap_live_xxxxxxxxxxxxxxxx";

async function searchAddresses(query) {
  if (!query || query.trim().length < 3) return { count: 0, suggestions: [] };
  const res = await fetch(
    "https://autopostcode.com/api/public/autocomplete?q=" +
      encodeURIComponent(query),
    { headers: { "x-api-key": API_KEY } }
  );
  if (!res.ok) throw new Error("Search failed: " + res.status);
  return res.json();
}

searchAddresses("86 marland fold").then(console.log);

{
  "query": "10 downing",
  "count": 1,
  "suggestions": [
    {
      "suggestion": "10 Downing Street, London, Greater London, SW1A 2AA",
      "postcode": "SW1A 2AA",
      "line1": "10 Downing Street",
      "line2": "",
      "line3": "",
      "town": "London",
      "county": "Greater London",
      "country": "United Kingdom"
    }
  ],
  "credits_remaining": 1584
}

// Drop-in vanilla-JS address autocomplete.
// Renders a search box, debounces input, calls the API, shows a
// dropdown, and populates address fields on select.
//
// Expected HTML:
//   <input id="apc-search" placeholder="Start typing your address" />
//   <ul id="apc-suggestions"></ul>
//   <input id="line1" /> <input id="line2" /> <input id="town" />
//   <input id="county" /> <input id="postcode" />

const API_KEY = "ap_live_xxxxxxxxxxxxxxxx";
const ENDPOINT = "https://autopostcode.com/api/public/autocomplete";

const input = document.getElementById("apc-search");
const list  = document.getElementById("apc-suggestions");

let timer, controller;

input.addEventListener("input", () => {
  clearTimeout(timer);
  timer = setTimeout(() => runSearch(input.value.trim()), 300);
});

async function runSearch(q) {
  list.innerHTML = "";
  if (q.length < 3) return;

  if (controller) controller.abort();
  controller = new AbortController();

  try {
    const res = await fetch(
      ENDPOINT + "?q=" + encodeURIComponent(q),
      { headers: { "x-api-key": API_KEY }, signal: controller.signal }
    );
    const data = await res.json();
    if (!data.suggestions?.length) {
      list.innerHTML = "<li>No addresses found.</li>";
      return;
    }
    for (const s of data.suggestions) {
      const li = document.createElement("li");
      li.textContent = s.suggestion;
      li.onclick = () => fill(s);
      list.appendChild(li);
    }
  } catch (err) {
    if (err.name !== "AbortError") {
      list.innerHTML = "<li>Unable to search addresses.</li>";
    }
  }
}

function fill(addr) {
  document.getElementById("line1").value    = addr.line1 || "";
  document.getElementById("line2").value    = addr.line2 || "";
  document.getElementById("town").value     = addr.town  || "";
  document.getElementById("county").value   = addr.county || "";
  document.getElementById("postcode").value = addr.postcode || "";
  input.value = addr.suggestion;
  list.innerHTML = "";
}

// React hook — address autocomplete with debounce + abort.
import { useEffect, useRef, useState } from "react";

const API_KEY = import.meta.env.VITE_AUTOPOSTCODE_KEY!;
const ENDPOINT = "https://autopostcode.com/api/public/autocomplete";

export function useAddressSearch(query: string) {
  const [suggestions, setSuggestions] = useState<any[]>([]);
  const [status, setStatus] = useState<"idle"|"loading"|"empty"|"error">("idle");
  const ctrl = useRef<AbortController | null>(null);

  useEffect(() => {
    if (query.trim().length < 3) { setSuggestions([]); setStatus("idle"); return; }
    const t = setTimeout(async () => {
      ctrl.current?.abort();
      ctrl.current = new AbortController();
      setStatus("loading");
      try {
        const res = await fetch(
          ENDPOINT + "?q=" + encodeURIComponent(query),
          { headers: { "x-api-key": API_KEY }, signal: ctrl.current.signal }
        );
        const data = await res.json();
        setSuggestions(data.suggestions ?? []);
        setStatus(data.suggestions?.length ? "idle" : "empty");
      } catch (e: any) {
        if (e.name !== "AbortError") setStatus("error");
      }
    }, 300);
    return () => clearTimeout(t);
  }, [query]);

  return { suggestions, status };
}

# AutoPostcode — one-shot setup recipe (for AI agents)
#
# Goal: add a live UK address search box to a checkout / signup form.
# Data returned: PAF-verified UK addresses (line1, line2, town, county, postcode).
#
# 1. Get a key at https://autopostcode.com  (starts with ap_live_)
# 2. Store as VITE_AUTOPOSTCODE_KEY (or proxy through your backend).
# 3. Call the autocomplete endpoint on every debounced keystroke:
#
#    GET https://autopostcode.com/api/public/autocomplete?q=<user_text>
#    Header: x-api-key: ap_live_...
#
# 4. Render response.suggestions[] as a dropdown.
# 5. On click, populate line1 / line2 / town / county / postcode fields.
#
# For a postcode-first flow (button-triggered) use instead:
#    GET https://autopostcode.com/api/public/lookup?postcode=<postcode>
#    Header: x-api-key: ap_live_...
#
# Both endpoints:
#   - Cost 1 credit per successful call (no-result calls are free).
#   - Support GET (query string) and CORS from any origin.
#   - Return JSON with the same address field names.