PostcodeClient

Gatepost\Postcode\Client\PostcodeClient

Calls NIPOST’s postcode gateway with your own API key. Each call blocks until it has a result or a PostcodeException. A call that fails for a reason that can pass, such as a 503, is tried again, up to maxRetries times. The client keeps no result unless cacheTtlMs is above 0.

Unofficial. Not made or endorsed by NIPOST.

$client = new PostcodeClient(
    new \GuzzleHttp\Client(['timeout' => 15]),
    new \GuzzleHttp\Psr7\HttpFactory(),
    apiKey: \getenv('NIPOST_API_KEY') ?: null,
    timeoutMs: 15000,
);

Methods

__construct()

public function __construct(
    Psr\Http\Client\ClientInterface $transport,
    Psr\Http\Message\RequestFactoryInterface $requestFactory,
    ?string $apiKey = null,
    string $baseUrl = 'https://api.postcode.gov.ng',
    ?int $timeoutMs = null,
    int $maxRetries = 2,
    int $cacheTtlMs = 0,
    ?Psr\SimpleCache\CacheInterface $cache = null,
)

Parameters

Name	Meaning
$transport	A PSR-18 HTTP client. PSR-18 has no timeout, so set the timeout of the transport and pass the same value as timeoutMs. 15 s covers autocomplete. The client reads a failed attempt as a timeout when it took timeoutMs or more, and as a network_error when it took less.
$requestFactory	A PSR-17 factory for the requests.
$apiKey	The key for the X-API-Key header. With null, the client sends no key, and the gateway answers 401.
$baseUrl	The gateway’s address.
$timeoutMs	The longest wait for one attempt, for every call. A failed attempt that took this long is a timeout. With null, it is 8000, and 15000 for autocomplete. Pass the timeout of the transport.
$maxRetries	The most retries after the first attempt.
$cacheTtlMs	How long the client keeps a result. 0 turns the cache off.
$cache	A PSR-16 cache for the results. The client needs one when cacheTtlMs is above 0.

Throws

• InvalidArgumentException When an option is out of range, the key is empty, or cacheTtlMs is above 0 with no cache.

lookup()

public function lookup(Postcode|string $code, int $level = 1): Client\LookupResult

Asks the gateway what it knows about a postcode. The client checks the code with Postcode::parse() first, and sends no request for a code that fails. Levels above 1 use credits, and a key holds a level grant. A level above the grant fails with Forbidden. The shapes of levels 2 to 5 follow NIPOST’s docs. Gatepost has seen only level 1.

$result = $client->lookup('fc 01 z99 zz 01');
$result->valid; // true
echo $result->postcode->canonical; // FC-01-Z99-ZZ-01

Parameters

Name	Meaning
$code	A full postcode, as text or as a parsed postcode.
$level	The lookup level, from 1 to 5. PHP’s own type check refuses a value that is not a whole number.

Throws

• PostcodeException For a code that fails the check, for a level outside 1 to 5, and for each failure of the gateway. The client sends no request for bad input.

reverse()

public function reverse(float $lat, float $lng, ?float $maxDistanceM = null): Client\ReverseResult

Finds the postcode at a point, such as a GPS fix. A point with no postcode within the radius is a result with found false, not an error.

$result = $client->reverse(9.0, 7.0);
echo $result->unit?->postcode->canonical; // FC-01-Z99-ZZ-01
echo $result->area; // FC-01-Z99-ZZ

Parameters

Name	Meaning
$lat	The latitude in degrees, from -90 to 90.
$lng	The longitude in degrees, from -180 to 180.
$maxDistanceM	The radius in metres, from 0 to 250. With null, the gateway applies its own default. The gateway cuts a larger radius to 250 without a sign, so the client refuses it.

Throws

• PostcodeException For a number outside its range or not finite, and for each failure of the gateway. The client sends no request for bad input.

autocomplete()

public function autocomplete(string $q): Client\AutocompleteResult

Suggests ways to complete the segment that the user types. The client normalises the text with Postcode::normalize(). It sends no request for text that is empty, longer than a postcode, or holds a character other than A to Z and 0 to 9. A timeout ends the call without a retry, because the next keystroke replaces it. The call waits 15 s by default, so set the timeout of the transport to 15 s and pass the same timeoutMs. With a shorter transport timeout, the failure reads as a network_error, and the client retries it.

$result = $client->autocomplete('fc01z');
echo $result->segment->value; // district
echo $result->suggestions[0]->postcode?->canonical; // FC-01-Z99

Parameters

Name	Meaning
$q	The text that the user typed.

Throws

• PostcodeException For text that fails the check, and for each failure of the gateway.

clearCache()

public function clearCache(): void

Removes every result that any client of the same cache kept, also the results of a client with another API key. The caller’s other cache entries stay. A request that started before this call keeps no result. A failure of the cache passes to the caller.

$client->clearCache();