PostcodeClient

Calls NIPOST’s postcode gateway. A client retries, waits, shares identical calls and limits its parallel requests as spec/client.md says. It sends only the requests that its caller makes, and it never logs.

Example

import { PostcodeClient } from '@gatepost/client';

const client = new PostcodeClient({ apiKey: process.env['NIPOST_API_KEY'] });
const result = await client.lookup('fc 01 z99 zz 01');
result.postcode.canonical; // 'FC-01-Z99-ZZ-01'

Constructors

Constructor

new PostcodeClient(options?): PostcodeClient

Makes a client. Two clients share nothing, so each can have its own key and settings.

Parameters

options?

ClientOptions = {}

The key, the gateway’s address, the transport, the timeout, the retries and the cache time. Each one is optional.

Returns

PostcodeClient

Throws

RangeError for a timeoutMs of 0 or less, a maxRetries that is not a whole number of 0 or more, a cacheTtlMs that is negative or not finite, or an empty apiKey.

Throws

TypeError for a secret key in a web page.

Methods

autocomplete()

autocomplete(q, options?): Promise<AutocompleteResult>

Asks the gateway for the values of the segment that a user is typing. Empty text sends no request, because the gateway does not answer it. A timeout gets no retry, because the next keystroke replaces the call.

Parameters

q

string

The text that the user typed, in any spacing and letter case.

options?

Readonly<{ signal?: AbortSignal; }> = {}

A signal that cancels the call.

Returns

Promise<AutocompleteResult>

The active segment and the gateway’s values for it.

Throws

PostcodeError invalid_input for text that is empty, too long or not letters and digits, and the code that the status map gives for a failed response.

Example

import { PostcodeClient } from '@gatepost/client';

const client = new PostcodeClient({ apiKey: process.env['NIPOST_API_KEY'] });
const result = await client.autocomplete('fc 01 z');
result.segment; // 'district'

---

clearCache()

clearCache(): void

Removes every kept result, so that the next call of each kind sends a request.

Returns

void

Example

import { PostcodeClient } from '@gatepost/client';

const apiKey = process.env['NIPOST_API_KEY'];
const client = new PostcodeClient({ apiKey, cacheTtlMs: 60_000 });
await client.lookup('FC-01-Z99-ZZ-01');
client.clearCache();

---

lookup()

lookup(code, options?): Promise<LookupResult>

Asks the gateway about one postcode. The core parses the code first, and a code that does not parse as a whole postcode sends no request. A postcode that the gateway does not know gives a result with valid false, not an error.

Parameters

code

string | Postcode

The postcode as text in any form, or as a postcode that parse returned.

options?

Readonly<{ level?: LookupLevel; signal?: AbortSignal; }> = {}

The lookup level, which is 1 by default, and a signal that cancels the call.

Returns

Promise<LookupResult>

The facts about the postcode, up to the level that the key holds.

Throws

PostcodeError invalid_input for a code that does not parse, and the code that the status map gives for a failed response.

Example

import { PostcodeClient } from '@gatepost/client';

const client = new PostcodeClient({ apiKey: process.env['NIPOST_API_KEY'] });
const result = await client.lookup('FC-01-Z99-ZZ-01', { level: 2 });
result.levelRequested; // 2
if (result.levelReceived >= 2) {
  result.administrativeAddress?.stateName;
}

---

reverse()

reverse(lat, lng, options?): Promise<ReverseResult>

Asks the gateway for the unit nearest to a coordinate. A point with no postcode in range gives a result with found false, not an error.

Parameters

lat

number

The latitude in degrees.

lng

number

The longitude in degrees.

options?

Readonly<{ maxDistanceM?: number; signal?: AbortSignal; }> = {}

The radius maxDistanceM in metres, which the gateway sets to 25 when it is missing, and a signal that cancels the call.

Returns

Promise<ReverseResult>

What the gateway found.

Throws

PostcodeError with the code that the status map gives for a failed response.

Example

import { PostcodeClient } from '@gatepost/client';

const client = new PostcodeClient({ apiKey: process.env['NIPOST_API_KEY'] });
const result = await client.reverse(9, 7, { maxDistanceM: 250 });
if (result.unit !== null) {
  result.unit.postcode.canonical;
}