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&session=s_abc123" \
  -H "x-api-key: ap_live_xxxxxxxxxxxxxxxx"

// Address Autocomplete — Fetchify-style search-as-you-type.
// BILLING: one address search = one credit. Send the SAME session id with
// every keystroke of a single search; reset it when the user picks an
// address or clears the field. Keystrokes after the first are free.
const API_KEY = "ap_live_xxxxxxxxxxxxxxxx";

let session = null;
const newSession = () =>
  "s_" + Date.now().toString(36) + Math.random().toString(36).slice(2, 10);
export const resetSession = () => { session = null; };

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

// Debounce input by 300ms, then:
searchAddresses("86 marland fold").then(console.log);
// After the user selects an address (or clears the input): resetSession();

{
  "query": "aberdeen",
  "count": 9,
  "groups": [
    {
      "token": "eyJzIjoiVW5pb24gU3RyZWV0IiwidCI6IkFiZXJkZWVuIn0",
      "label": "Union Street, Aberdeen",
      "postcode": "",
      "count": 42
    }
  ],
  "suggestions": [
    {
      "suggestion": "AB10 1AA — 20, Union Street, Aberdeen",
      "label": "20, Union Street, Aberdeen",
      "postcode": "AB10 1AA",
      "line1": "20 Union Street",
      "line2": "",
      "line3": "",
      "town": "Aberdeen",
      "county": "Aberdeenshire",
      "country": "United Kingdom"
    }
  ],
  "session": "s_lx8f2k9a1b2c",
  "credits_charged": 1,
  "credits_remaining": 1584
}

curl "https://autopostcode.com/api/public/autocomplete?group=eyJzIjoiVW5pb24…" \
  -H "x-api-key: ap_live_xxxxxxxxxxxxxxxx"

{
  "group": "eyJzIjoiVW5pb24…",
  "count": 42,
  "suggestions": [
    { "suggestion": "AB10 1AA — 1, Union Street, Aberdeen", "postcode": "AB10 1AA", "label": "1, Union Street, Aberdeen", "line1": "1 Union Street", "town": "Aberdeen", "county": "Aberdeenshire" },
    { "suggestion": "AB10 1AA — 2, Union Street, Aberdeen", "postcode": "AB10 1AA", "label": "2, Union Street, Aberdeen", "line1": "2 Union Street", "town": "Aberdeen", "county": "Aberdeenshire" }
  ]
}

// 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>&session=<search_session_id>
#    Billing: ONE credit per search session, not per keystroke. Generate a
#    session id when a search starts, send it with every keystroke, reset it
#    when an address is selected or the input is cleared. Debounce 300ms.
#    A session id stays free for 1 hour; there is no inactivity timeout, so
#    you control when a session ends by resetting the id.
#    Header: x-api-key: ap_live_...
#
# 4. Render response.groups[] FIRST as "View {count} addresses at {label} ›" rows,
#    then response.suggestions[] as one-line "{POSTCODE} — {label}" rows.
# 5. On group click: GET .../autocomplete?group=<token> (opaque, pass verbatim,
#    no credit charge). Replace dropdown with returned suggestions.
# 6. After opening a group, filter locally in the browser as the user keeps
#    typing. Only issue a new global ?q= search when the local filter is empty
#    OR the input is cleared.
# 7. On address click, populate line1 / line2 / town / county / postcode fields
#    and keep the full raw address object on the form.
#
# 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; group
#     expansions are free).
#   - Support GET (query string) and CORS from any origin.
#   - Return JSON with the same address field names.