@mountainpass/addressr-core

Framework-agnostic HATEOAS client for the Addressr Australian address API. Use this to build your own address search UI in any framework, or pair it with a framework package:

• React: @mountainpass/addressr-react
• Svelte: @mountainpass/addressr-svelte
• Vue: @mountainpass/addressr-vue

Install

npm install @mountainpass/addressr-core

Usage

import { createAddressrClient, parseHighlight } from '@mountainpass/addressr-core';

const client = createAddressrClient({
  apiUrl: 'https://api.addressr.io/',
  // Or use RapidAPI:
  // apiKey: 'your-rapidapi-key',
});

// Search
const page = await client.searchAddresses('1 george st');
console.log(page.results);   // AddressSearchResult[]
console.log(page.nextLink);  // Link | null

// Paginate
if (page.nextLink) {
  const page2 = await client.fetchNextPage(page.nextLink);
}

// Get full detail
const detail = await client.getAddressDetail('GANSW123');
console.log(detail.structured);  // { street, locality, state, postcode, ... }
console.log(detail.geocoding);   // { latitude, longitude, ... }

// Safe highlight rendering
const segments = parseHighlight('<em>1</em> <em>GEORGE</em> ST');
// [{ text: '1', highlighted: true }, { text: ' ', highlighted: false }, ...]

API

createAddressrClient(options)

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | -- | RapidAPI key. Omit for direct API access. | | apiUrl | string | "https://addressr.p.rapidapi.com/" | API root URL | | apiHost | string | "addressr.p.rapidapi.com" | RapidAPI host header | | retry | RetryOptions \| false | { maxRetries: 2, baseDelayMs: 500, maxDelayMs: 5000 } | Retry config, or false to disable | | fetchImpl | typeof fetch | globalThis.fetch | Custom fetch (for testing) |

Returns an AddressrClient with:

| Method | Returns | Description | |--------|---------|-------------| | searchAddresses(query, signal?) | Promise<SearchPage<AddressSearchResult>> | Search addresses. Returns results + HATEOAS next link. | | searchPostcodes(query, signal?) | Promise<SearchPage<PostcodeSearchResult>> | Search postcodes. | | searchLocalities(query, signal?) | Promise<SearchPage<LocalitySearchResult>> | Search suburbs/towns. | | searchStates(query, signal?) | Promise<SearchPage<StateSearchResult>> | Search states/territories. | | fetchNextPage(nextLink, signal?) | Promise<SearchPage<T>> | Follow a next-page link relation. | | getAddressDetail(pid, signal?, searchPage?, index?) | Promise<AddressDetail> | Get full address detail. Follows canonical link when search context provided. |

SearchPage<T>

Generic over the result type. Defaults to AddressSearchResult for backward compatibility.

{
  results: T[];           // Array of search results
  nextLink: Link | null;  // HATEOAS link to next page, or null
}

Postcode, locality, and state search

In addition to searchAddresses, the client exposes three narrower search methods for when a form needs only a postcode, suburb, or state. Each shares the same HATEOAS root discovery, retry behaviour, and abort semantics as searchAddresses.

Postcodes

const page = await client.searchPostcodes('2000');
// page.results[0] is { postcode: '2000', localities: [{ name: 'SYDNEY' }, ...] }

Localities

const page = await client.searchLocalities('sydney');
// page.results[0] is { name: 'SYDNEY', state: { abbreviation: 'NSW', name: 'NEW SOUTH WALES' }, postcode: '2000', score, pid }

States

const page = await client.searchStates('NSW');
// page.results[0] is { name: 'NEW SOUTH WALES', abbreviation: 'NSW' }

RetryOptions

{
  maxRetries?: number;   // Default: 2
  baseDelayMs?: number;  // Default: 500 — exponential backoff base
  maxDelayMs?: number;   // Default: 5000 — backoff cap
}

Failed requests are retried with exponential backoff and jitter. Only network errors and 5xx responses are retried -- 4xx errors fail immediately. Pass retry: false to disable.

parseHighlight(html)

Safely parses Elasticsearch <em> highlight tags into segments. No innerHTML, no XSS.

parseHighlight(html: string): HighlightSegment[]
// HighlightSegment = { text: string; highlighted: boolean }

Architecture

• HATEOAS -- API root discovery via RFC 8288 Link headers, no hardcoded paths
• Pagination -- follows next link relations, accumulates results across pages
• Canonical links -- getAddressDetail follows canonical link from search results when available, falls back to URL construction
• Root caching -- API root fetched once per client instance
• Abort support -- all methods accept AbortSignal for cancellation

License

Apache-2.0