# FastAddress UK — Complete AI Agent Integration Reference

FastAddress UK is a high-performance UK address autocomplete, postcode lookup, and geocoding platform providing sub-15ms response latencies across 21.1+ million verified UK property records.

---

## 1. Official TypeScript SDK (@ahm-labs/fast-address-uk)

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

### TypeScript Data Interfaces
```typescript
export interface AddressResult {
  id: number;              // Unique database identifier
  address_string: string;  // Formatted address line suitable for delivery labels
  postcode: string;        // Official Royal Mail UK postcode (e.g. "SW1A 1AA")
  latitude: number;        // WGS84 GPS Latitude
  longitude: number;       // WGS84 GPS Longitude
  uprn: number | null;     // Ordnance Survey 12-digit Unique Property Reference Number
}

export interface LookupOptions {
  apiKey?: string;
  baseUrl?: string;
  limit?: number;
  signal?: AbortSignal;
  timeoutMs?: number;
  headers?: Record<string, string>;
}
```

---

## 2. React / Next.js Integration Hook

Import from the `@ahm-labs/fast-address-uk/react` subpath.
Handles internal debouncing (default 200ms) and automatic cancellation of stale in-flight requests.

```tsx
'use client';

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

export function UkAddressInput({ onAddressSelect }: { onAddressSelect?: (addr: AddressResult) => void }) {
  const { query, results, isLoading, error, search, clear } = useFastAddress({
    debounceMs: 200,
    minQueryLength: 2
  });

  return (
    <div className="address-autocomplete-wrapper">
      <input
        type="text"
        value={query}
        onChange={(e) => search(e.target.value)}
        placeholder="Enter postcode or street (e.g. SW1A 1AA)..."
        className="address-search-input"
      />
      {isLoading && <div className="loading-spinner">Searching...</div>}
      {error && <div className="error-message">Failed to load addresses</div>}

      {results.length > 0 && (
        <ul className="address-suggestions-list">
          {results.map((addr) => (
            <li
              key={addr.id || addr.uprn}
              onClick={() => {
                onAddressSelect?.(addr);
                clear();
              }}
            >
              <strong>{addr.address_string}</strong>
              <span>{addr.postcode} • UPRN: {addr.uprn || 'N/A'}</span>
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}
```

---

## 3. Vanilla JavaScript / Node.js Backend

```typescript
import { lookupAddress, createFastAddressClient } from '@ahm-labs/fast-address-uk';

// One-off lookup
const results = await lookupAddress('10 Downing Street', { limit: 5 });
console.log(results[0].address_string, results[0].uprn, results[0].postcode);

// Reusable client instance
const client = createFastAddressClient({
  apiKey: process.env.FAST_ADDRESS_KEY,
  defaultLimit: 10
});

const addresses = await client.lookup('SW1A 1AA');
```

---

## 4. Raw HTTP REST API Specification

### Endpoint
`GET https://fastaddress.ahm-labs.com/api/v1/autocomplete?q={query}&limit={limit}`

### Query Parameters
- `q` (string, required): Partial or full postcode, street name, house number, or city (minimum 2 characters).
- `limit` (integer, optional): Maximum suggestions to return (default: 10, max: 50).

### Sample cURL
```bash
curl -X GET "https://fastaddress.ahm-labs.com/api/v1/autocomplete?q=10+Downing+Street" \
  -H "Accept: application/json"
```

### Sample JSON Response
```json
[
  {
    "id": 100121005441,
    "address_string": "10 Downing Street, Wiltshire",
    "postcode": "SN14 0AA",
    "latitude": 51.461924,
    "longitude": -2.12757,
    "uprn": 100121005441
  },
  {
    "id": 100030048320,
    "address_string": "10 Downing Street, South Normanton, Bolsover",
    "postcode": "DE55 2HE",
    "latitude": 53.106679,
    "longitude": -1.340282,
    "uprn": 100030048320
  }
]
```

---

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

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

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