PHP API Client wrapper for MoJ Postcode Info API

This package's canonical repository appears to be gone and the package has been frozen as a result.

v4.0.0 2016-05-13 13:40 UTC


PHP API Client for the MoJ DS PostcodeInfo service.


The Postcode Lookup PHP Client is based on a PSR-7 HTTP model. You therefore need to pick your preferred HTTP Client library to use.

We will show examples here using the Guzzle v6 Adapter.

Setup instructions are also available for Curl and Guzzle v5.


The Postcode Lookup PHP Client can be installed with Composer. Run this command:

composer require php-http/guzzle6-adapter ministryofjustice/postcodeinfo-client-php



You will need an authentication token (auth token). If you're using MOJ DS's Postcode Info server, you can get a token by emailing with a brief summary of:

  • who you are
  • what project you're going to be using it on
  • roughly how many lookups you expect to do per day

If you're running your own server, see for instructions on how to create a token.


Assuming you've installed the package via Composer, the Postcode Lookup PHP Client will be available via the autoloader.

Create a (Guzzle v6 based) instance of the Client using:

$client = new \MinistryOfJustice\PostcodeInfo\Client([
    'apiKey'        => '{your api key}',
    'httpClient'    => new \Http\Adapter\Guzzle6\Client

You are then able to access the Postcode Lookup API using $client.

If you need to access an environment other than production, you can pass the base URL in via the baseUrl key in the constructor:

'baseUrl' => '{api base url}'

Return a list of addresses for a postcode

// Return a list of addresses
$addresses = $client->lookupPostcodeAddresses('SW19 5AL');

// Check if any addresses were found
$found = !empty($addresses);

// Count the addresses found
$numberFound = count($addresses);

// Iterate over the returned addresses
foreach ($addresses as $address) {

		// Available properties include...

        // Coordinate info is under...


Return metadata about a postcode

$metadata = $client->lookupPostcodeMetadata('AB12 4YA');

// You then have access to the following properties...




To run the tests, add a file called spec/api_key. Inside this file place the API token for the postcode info service.

Install the composer dependencies

php composer.phar install

Then, from the root of the repository

bin/phpspec run --format=pretty -vvv --stop-on-failure


The Postcode Lookup PHP Client is released under the MIT license, a copy of which can be found in LICENSE.