Getting Started

Stable

Sign up, get your API key, and make your first address lookup in under five minutes.

Create your account

Head to snapaddress.io/signup and create a free account. No credit card required — you get 100 free lookups to start, valid for 3 months.

A lookup is a request that returns address data: a full postcode lookup, or an address selected from autocomplete. Searching as the customer types is free, so a completed address search normally uses one lookup. Opening a second suggestion uses another, and so does each further page of a postcode with more than 100 addresses. Which endpoints spend a credit.

You will receive a magic link via email. Click it to confirm your account and access the dashboard.

Get your API key

After you confirm your email, the welcome screen asks for your address and whether you're a business. Once you've saved those, your first API key is created and shown. You don't have to copy it straight away: the full key stays available to copy from the API Keys page in the dashboard.

You can create additional keys from the same page — one per store or environment is a good pattern.

Tip

Store your API key as an environment variable (e.g. SNAPADDRESS_API_KEY). Never commit it to version control.

Make your first request

Send a GET request with your postcode and API key:

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.snapaddress.io/v1/postcodes/SW1A2AA"

You will receive a JSON response containing all addresses at that postcode:

{
  "postcode": "SW1A 2AA",
  "addresses": [
    {
      "line_1": "Prime Minister & First Lord Of The Treasury",
      "line_2": "10 Downing Street",
      "line_3": "",
      "town": "LONDON",
      "county": "Greater London",
      "postcode": "SW1A 2AA",
      "country": "England",
      "udprn": "23747771",
      "formatted_address": "Prime Minister & First Lord Of The Treasury, 10 Downing Street, LONDON, SW1A 2AA",
      "organisation": "Prime Minister & First Lord Of The Treasury",
      "building_number": "10",
      "street": "Downing Street",
      "type": "commercial",
      ...
    }
  ],
  "count": 1,
  "page": 1,
  "limit": 100,
  "total": 1,
  "next_page": null
}

Abridged — each address also carries the other structured fields, a postal label and a Royal Mail barcode. See the Response Format for every field.

Using the API in your code

JavaScript / Node.js

const postcode = "SW1A 2AA";
 
const response = await fetch(
  `https://api.snapaddress.io/v1/postcodes/${encodeURIComponent(postcode)}`,
  { headers: { "x-api-key": process.env.SNAPADDRESS_API_KEY } }
);
 
const data = await response.json();
console.log(data.addresses);

Python

import os
import requests
 
postcode = "SW1A 2AA"
api_key = os.environ["SNAPADDRESS_API_KEY"]
 
response = requests.get(
    f"https://api.snapaddress.io/v1/postcodes/{postcode}",
    headers={"x-api-key": api_key}
)
 
data = response.json()
print(data["addresses"])

PHP

$postcode = 'SW1A 2AA';
$apiKey = getenv('SNAPADDRESS_API_KEY');
 
$url = "https://api.snapaddress.io/v1/postcodes/" . urlencode($postcode);
$opts = ["http" => ["header" => "x-api-key: " . $apiKey]];
$response = json_decode(file_get_contents($url, false, stream_context_create($opts)), true);
 
print_r($response['addresses']);

Address autocomplete

The autocomplete endpoint lets users search by partial postcode, street, or organisation. It requires a minimum of 2 characters — single-character queries return a 400 error.

Keep your API key on your server: the browser calls a route on your backend, and that route calls SnapAddress with the key from an environment variable. (The API doesn't accept browser requests from other sites, and a key in client-side code can be read by anyone.) For example, a Next.js route handler:

// app/api/address-suggest/route.js — runs on your server
export async function GET(request) {
  const q = new URL(request.url).searchParams.get("q") ?? "";
  // Enforce the 2-character minimum before calling the API
  if (q.trim().length < 2) return Response.json({ suggestions: [] });
 
  const res = await fetch(
    `https://api.snapaddress.io/v1/autocomplete?q=${encodeURIComponent(q)}`,
    { headers: { "x-api-key": process.env.SNAPADDRESS_API_KEY } }
  );
  return Response.json(await res.json(), { status: res.status });
}

In the browser, check text.length >= 2 before calling your route, and show a hint like "Keep typing for results..." instead.

Each suggestion has a type:

  • "postcode" — fetch its addresses with GET /v1/postcodes/{postcode}.
  • "address" — a single matching address; fetch it with GET /v1/addresses/{udprn} using the suggestion's udprn.

Autocomplete is free; the follow-up call is the lookup that spends a credit. Proxy those through your server the same way.

Next steps