UK postcode geocoding API: convert postcodes to coordinates (Python & JS)

curl "https://api.homedata.co.uk/postcode-profile/?postcode=SW1A1AA" \
  -H "Authorization: Api-Key hd_live_your_key_here"

# {
#   "postcode": "SW1A 1AA",
#   "outcode": "SW1A",
#   "location": { "lat": 51.501008, "lng": -0.141588 },
#   ...
# }

curl "https://api.homedata.co.uk/address/postcode/SW1A2AA/" \
  -H "Authorization: Api-Key hd_live_your_key_here"

# { "postcode": "SW1A 2AA", "count": 1,
#   "addresses": [ { "uprn": 100023336956, "uprn_token": "gAAAAABm4xK…",
#                    "address": "PRIME MINISTER & FIRST LORD OF THE TREASURY, 10 DOWNING STREET, LONDON, SW1A 2AA",
#                    "building_number": "10", "street": "Downing Street", "town": "London" } ] }

curl "https://api.homedata.co.uk/property/100023336956/address/" \
  -H "Authorization: Api-Key hd_live_your_key_here"

{
  "uprn": 100023336956,
  "full_address": "10 DOWNING STREET, LONDON, SW1A 2AA",
  "address_line_1": "10 Downing Street",
  "building_number": "10",
  "street_name": "Downing Street",
  "town_name": "London",
  "postcode": "SW1A 2AA",
  "outward_postcode": "SW1A",
  "latitude": 51.5033,
  "longitude": -0.1276
}

import requests
import csv
import time

API_KEY = "hd_live_your_key_here"
BASE_URL = "https://api.homedata.co.uk"

class AmbiguousPostcode(Exception):
    """A postcode identified more than one property and no building was given."""

    def __init__(self, postcode: str, addresses: list[dict]):
        self.postcode = postcode
        self.addresses = addresses
        super().__init__(
            f"{postcode} has {len(addresses)} registered addresses. "
            f"Pass building= to choose one, e.g. building=\"{addresses[0]['address']}\"."
        )


def geocode_address(postcode: str, building: str | None = None) -> dict | None:
    """
    Convert a postcode plus a building to that property's exact coordinates.
    Two calls: addresses at the postcode (2 tokens), then the property (5 tokens).

    A postcode is NOT a property. Most postcodes cover 15-100 addresses, so this
    refuses to guess: pass `building` unless the postcode has exactly one address.
    Returns None if nothing matches; raises AmbiguousPostcode if you did not choose.
    """
    # Normalise: strip spaces for the URL path
    clean = postcode.replace(" ", "").upper()

    # Step 1: postcode -> addresses, each with a UPRN
    resp = requests.get(
        f"{BASE_URL}/address/postcode/{clean}/",
        headers={"Authorization": f"Api-Key {API_KEY}"},
        timeout=10,
    )
    if resp.status_code == 404:
        return None  # invalid or terminated postcode
    resp.raise_for_status()

    addresses = resp.json().get("addresses", [])
    if not addresses:
        return None  # postcode is live but has no registered addresses

    if building is not None:
        wanted = building.strip().casefold()
        matches = [a for a in addresses if wanted in a["address"].casefold()]
        if len(matches) != 1:
            return None  # no match, or still ambiguous - do not pick one
        uprn = matches[0]["uprn"]
    elif len(addresses) == 1:
        uprn = addresses[0]["uprn"]
    else:
        # Silently taking addresses[0] here is the exact error this article is
        # about: you would map a neighbour and never find out.
        raise AmbiguousPostcode(postcode, addresses)

    # Step 2: UPRN -> coordinates
    detail = requests.get(
        f"{BASE_URL}/property/{uprn}/address/",
        headers={"Authorization": f"Api-Key {API_KEY}"},
        timeout=10,
    )
    detail.raise_for_status()

    data = detail.json()
    return {
        "postcode": data.get("postcode", postcode),
        "uprn": uprn,
        "address": data.get("full_address"),
        "latitude": data.get("latitude"),
        "longitude": data.get("longitude"),
    }


def batch_geocode(locations: list[tuple[str, str]], output_csv: str):
    """Geocode (postcode, building) pairs and write results to CSV."""
    results = []
    failed = []

    for i, (pc, building) in enumerate(locations, 1):
        print(f"  [{i}/{len(locations)}] Geocoding {building}, {pc}...", end=" ")

        try:
            result = geocode_address(pc, building)
            if result:
                results.append(result)
                print(f"→ ({result['latitude']}, {result['longitude']})")
            else:
                failed.append(pc)
                print("→ no single address matched")
        except AmbiguousPostcode as e:
            # Recorded as a failure, never resolved by guessing.
            failed.append(pc)
            print(f"→ {e}")
        except requests.exceptions.HTTPError as e:
            if e.response.status_code == 429:
                print("→ rate limited, waiting 2s...")
                time.sleep(2)
                # Retry once
                try:
                    result = geocode_address(pc, building)
                    if result:
                        results.append(result)
                except Exception:
                    failed.append(pc)
            else:
                failed.append(pc)
                print(f"→ error: {e}")

        # Pause briefly between requests
        time.sleep(0.5)

    # Write CSV
    if results:
        with open(output_csv, "w", newline="", encoding="utf-8") as f:
            writer = csv.DictWriter(f, fieldnames=results[0].keys())
            writer.writeheader()
            writer.writerows(results)

    print(f"\nDone: {len(results)} geocoded, {len(failed)} failed → {output_csv}")
    if failed:
        print(f"Failed postcodes: {', '.join(failed)}")

    return results


# Example: geocode office locations. Each needs a building, because a postcode
# on its own does not identify one - which is the whole argument of this article.
locations = [
    ("SW1A 2AA", "10 Downing Street"),
    ("EC2R 8AH", "Bank of England Museum Shop"),   # "Bank of England" alone matches four
    ("M1 1AE", "Flat 7, 113 Newton Street"),       # 21 flats share the building
]

batch_geocode(locations, "office_locations.csv")

const API_KEY = 'hd_live_your_key_here';
const BASE_URL = 'https://api.homedata.co.uk';

interface GeocodedAddress {
  postcode: string;
  uprn: number;
  latitude: number;
  longitude: number;
  fullAddress?: string;
}

/**
 * A postcode is not a property: most cover 15-100 addresses. Pass `building`
 * unless the postcode has exactly one, and this returns null rather than
 * guessing which neighbour you meant.
 */
async function geocodeAddress(
  postcode: string,
  building?: string,
): Promise<GeocodedAddress | null> {
  const clean = postcode.replace(/\s/g, '').toUpperCase();
  const headers = { 'Authorization': `Api-Key ${API_KEY}` };

  // Step 1: postcode -> addresses, each with a UPRN (2 tokens)
  const list = await fetch(`${BASE_URL}/address/postcode/${clean}/`, { headers });
  if (list.status === 404) return null;
  if (!list.ok) throw new Error(`API error: ${list.status}`);

  const { addresses = [] } = await list.json();
  if (addresses.length === 0) return null;

  let chosen;
  if (building !== undefined) {
    const wanted = building.trim().toLowerCase();
    const matches = addresses.filter(
      (a) => a.address.toLowerCase().includes(wanted),
    );
    if (matches.length !== 1) return null; // no match, or still ambiguous
    chosen = matches[0];
  } else if (addresses.length === 1) {
    chosen = addresses[0];
  } else {
    return null; // ambiguous - say which building you mean
  }

  // Step 2: UPRN -> coordinates (5 tokens)
  const uprn = chosen.uprn;
  const detail = await fetch(`${BASE_URL}/property/${uprn}/address/`, { headers });
  if (!detail.ok) throw new Error(`API error: ${detail.status}`);

  const data = await detail.json();
  return {
    postcode: data.postcode,
    uprn,
    latitude: data.latitude,
    longitude: data.longitude,
    fullAddress: data.full_address,
  };
}

/**
 * Calculate straight-line distance between two points (Haversine formula).
 * Returns distance in kilometres.
 */
function haversineKm(
  lat1: number, lng1: number,
  lat2: number, lng2: number
): number {
  const R = 6371; // Earth's radius in km
  const dLat = (lat2 - lat1) * Math.PI / 180;
  const dLng = (lng2 - lng1) * Math.PI / 180;
  const a =
    Math.sin(dLat / 2) ** 2 +
    Math.cos(lat1 * Math.PI / 180) *
    Math.cos(lat2 * Math.PI / 180) *
    Math.sin(dLng / 2) ** 2;
  return R * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
}

// Example: distance between two specific buildings
async function distanceBetween(
  from: [string, string],
  to: [string, string],
): Promise<string> {
  const [a, b] = await Promise.all([
    geocodeAddress(...from),
    geocodeAddress(...to),
  ]);

  if (!a || !b) return 'Could not resolve one or both addresses to a single property';

  const km = haversineKm(a.latitude, a.longitude, b.latitude, b.longitude);
  return `${a.fullAddress} → ${b.fullAddress}: ${km.toFixed(1)} km`;
}

// Run
distanceBetween(
  ['SW1A 2AA', '10 Downing Street'],
  ['EC2R 8AH', 'Bank of England Museum Shop'],  // 'Bank of England' alone matches four
).then(console.log);

curl "https://api.homedata.co.uk/address/postcode/SW1A2AA/" \
  -H "Authorization: Api-Key hd_live_your_key_here"

# Returns:
# {
#   "postcode": "SW1A 2AA",
#   "count": 1,
#   "addresses": [
#     { "uprn": 100023336956, "uprn_token": "gAAAAABm4xK…",
#       "address": "PRIME MINISTER & FIRST LORD OF THE TREASURY, 10 DOWNING STREET, LONDON, SW1A 2AA",
#       "building_number": "10", "street": "Downing Street", "town": "London" }
#   ]
# }
#
# Either uprn or uprn_token works in any {uprn} endpoint. Store the numeric
# uprn: the token is re-generated and will not match on a later call.

curl "https://api.homedata.co.uk/property/100023336956/address/" \
  -H "Authorization: Api-Key hd_live_your_key_here"

# Returns the address fields, including exact coordinates:
# {
#   "uprn": 100023336956,
#   "full_address": "10 DOWNING STREET, LONDON, SW1A 2AA",
#   "postcode": "SW1A 2AA",
#   "latitude": 51.5033,
#   "longitude": -0.1276
# }

import requests
import math

API_KEY = "hd_live_your_key_here"
BASE = "https://api.homedata.co.uk"

def haversine_km(lat1, lng1, lat2, lng2):
    """Calculate distance between two points in kilometres."""
    R = 6371
    dlat = math.radians(lat2 - lat1)
    dlng = math.radians(lng2 - lng1)
    a = (math.sin(dlat / 2) ** 2 +
         math.cos(math.radians(lat1)) *
         math.cos(math.radians(lat2)) *
         math.sin(dlng / 2) ** 2)
    return R * 2 * math.atan2(math.sqrt(a), math.sqrt(1 - a))


HEADERS = {"Authorization": f"Api-Key {API_KEY}"}


def coordinates_for(uprn: int) -> tuple[float, float, str]:
    """Exact coordinates for one property. 5 tokens."""
    data = requests.get(
        f"{BASE}/property/{uprn}/address/",
        headers=HEADERS,
        timeout=10,
    ).json()

    return data["latitude"], data["longitude"], data["full_address"]


def uprns_at(postcode: str) -> list[int]:
    """Every registered address at a postcode. 2 tokens."""
    clean = postcode.replace(" ", "").upper()
    addresses = requests.get(
        f"{BASE}/address/postcode/{clean}/",
        headers=HEADERS,
        timeout=10,
    ).json().get("addresses", [])

    return [a["uprn"] for a in addresses]


def distances_from(centre_uprn: int, candidate_postcode: str, radius_km: float = 1.0):
    """
    Distance from one property to every address at a postcode, nearest first.
    Filtering happens on your side: the API has no radius parameter.
    """
    centre_lat, centre_lng, centre_address = coordinates_for(centre_uprn)
    print(f"Centre: {centre_address} ({centre_lat}, {centre_lng})")

    nearby = []
    for uprn in uprns_at(candidate_postcode):
        lat, lng, address = coordinates_for(uprn)
        dist = haversine_km(centre_lat, centre_lng, lat, lng)
        if dist <= radius_km:
            nearby.append({"uprn": uprn, "address": address, "distance_km": round(dist, 2)})

    nearby.sort(key=lambda x: x["distance_km"])

    print(f"{len(nearby)} properties within {radius_km}km:")
    for p in nearby[:5]:
        print(f"  {p['address']}: {p['distance_km']}km")

    return nearby


# Example: how far is each address at SW1A 1AA from 10 Downing Street?
results = distances_from(100023336956, "SW1A 1AA", radius_km=2.0)