@ahm-labs/fast-address-uk ⚡

Ultra-fast, zero-dependency UK Address Autocomplete, Postcode Lookup, and Ordnance Survey UPRN Geocoding SDK with React hooks.

Features

• ⚡ Sub-15ms Latency: Query 21.1+ million UK addresses in under 15ms.
• 🎯 Official OS UPRN & Coordinates: Every address result includes the official Ordnance Survey Unique Property Reference Number and WGS84 GPS coordinates.
• ⚛️ First-Class React Hook: useFastAddress with built-in debouncing, race-condition mitigation, and state management.
• 🪶 Zero Dependencies: Core client uses native Web fetch (< 2KB gzipped).
• 🌐 Universal Runtime: Works out of the box in Node.js 18+, Bun, Deno, Cloudflare Workers, Next.js (App Router & Pages), Vite, Astro, and Browsers.
• 🛡️ Full TypeScript Support: Comprehensive exported types (AddressResult, LookupOptions, UseFastAddressOptions).

Installation

npm install @ahm-labs/fast-address-uk
# or
pnpm add @ahm-labs/fast-address-uk
# or
yarn add @ahm-labs/fast-address-uk

Quickstart

1. React / Next.js Hook (/react)

import React from 'react';
import { useFastAddress } from '@ahm-labs/fast-address-uk/react';

export function CheckoutAddressSearch() {
  const { query, results, isLoading, error, search, clear } = useFastAddress({
    debounceMs: 200 // optional, default: 200ms
  });

  return (
    <div className="address-picker">
      <input
        type="text"
        value={query}
        onChange={(e) => search(e.target.value)}
        placeholder="Enter postcode or street (e.g. SW1A 1AA)..."
      />

      {isLoading && <p>Searching...</p>}
      {error && <p>Error loading addresses</p>}

      <ul>
        {results.map((addr) => (
          <li key={addr.id || addr.uprn} onClick={() => console.log('Selected:', addr)}>
            <strong>{addr.address_string}</strong> ({addr.postcode})
            <small> • UPRN: {addr.uprn}</small>
          </li>
        ))}
      </ul>
    </div>
  );
}

2. Vanilla JavaScript / Node.js / Backend

import { lookupAddress } from '@ahm-labs/fast-address-uk';

// Query by partial street name or postcode
const addresses = await lookupAddress('10 Downing Street');

console.log(addresses);
/*
[
  {
    "id": 100121005441,
    "address_string": "10 Downing Street, Wiltshire",
    "postcode": "SN14 0AA",
    "latitude": 51.461924,
    "longitude": -2.12757,
    "uprn": 100121005441
  },
  ...
]
*/

3. Reusable Client Instance

import { createFastAddressClient } from '@ahm-labs/fast-address-uk';

const client = createFastAddressClient({
  apiKey: process.env.FAST_ADDRESS_API_KEY,
  defaultLimit: 5
});

const addresses = await client.lookup('M1 1AD');

4. Zero-Install Script Tag (WordPress, Shopify, Webflow)

<input type="text" id="postcode-input" placeholder="Start typing address..." />

<script src="https://fastaddress.ahm-labs.com/sdk/fast-address.min.js"></script>
<script>
  FastAddress.attachToInput('#postcode-input', {
    onSelect: function(address) {
      console.log('Selected address:', address.address_string);
      console.log('UPRN:', address.uprn);
      console.log('Coordinates:', address.latitude, address.longitude);
    }
  });
</script>

Response Object Interface

interface AddressResult {
  /** Unique database identifier */
  id: number;
  /** Formatted, human-readable address line */
  address_string: string;
  /** Official UK postcode (e.g. "SW1A 1AA") */
  postcode: string;
  /** WGS84 GPS Latitude */
  latitude: number;
  /** WGS84 GPS Longitude */
  longitude: number;
  /** Official Ordnance Survey Unique Property Reference Number */
  uprn: number | null;
}

API Keys & Pricing

FastAddress UK is free for initial development and prototypes. For high-volume production checkouts, grab an API key from our RapidAPI Portal.

License

MIT © AHM Labs