README

PHP client wrapper around the postcodes.io API service

Usage

Getting a PostCode

$postcode = PostCodeFactory::get('KY16 9SS');

or

$api = new Suilven\UKPostCodes\API();
$lookup = $this->api->lookup('KY16 9SS'');

Getting Nearby PostCodes

$postcode = PostCodeFactory::get('KY16 9SS');
$nearby = $postcode->nearest();

or

$api = new Suilven\UKPostCodes\API();
$nearest = $this->api->nearest('SW1A 2AA');

Bulk Lookup By PostCode

$api = new Suilven\UKPostCodes\API();
$postcodeObjects = $this->api->bulkLookup([
    'SW1A 2AA',
    'KY16 9SS',
    'KY11 3ED'
]);

Bulk Lookup By Coordinates

$api = new Suilven\UKPostCodes\API();

$coors = [
   [
     'latitude' => 51.50354,
     'longitude' => -0.127695,
   ],
   [
     'latitude' => 56.340349,
     'longitude' => -2.808787,
   ],
   [
     'latitude' => 56.03587,
     'longitude' => -3.500364,
   ],
];
$bulkReversed = $this->api->bulkReverseGeocoding($coors);

Bulk Lookup By Coordinates

Note that if the coordinates are outside of the UK, an empty array is returned by the API.

$api = new Suilven\UKPostCodes\API();
$postcodeObjects = $this->api->nearestPostcodesFromLongLat(0.629834723775309, 51.7923246977375);

Lookup Up A Terminated PostCode

Note that this will return a partially populated PostCode object.

$api = new Suilven\UKPostCodes\API();
$terminated = $this->api->lookupTerminated('AB1 0AA');

Lookup an Outward Code

An outcode is the part of a postcode prior to the space, e.g. KY16 in KY16 9SS

$api = new Suilven\UKPostCodes\API();
$lookup = $this->api->lookupOutwardCode('RH1');

Lookup Outward Code By Coordinates

$api = new Suilven\UKPostCodes\API();
$lookup = $this->api->nearestOutwardCodeFromLongLat(0.629834723775309, 51.7923246977375);

Find the Nearest Outward Code to a Given Outward Code

$api = new Suilven\UKPostCodes\API();
$nearest = $this->api->nearestOutwardCode('RH1');

Autocomplete a PostCode

$api = new Suilven\UKPostCodes\API();
$autocompletedPostCodes = $this->api->partial('SW16');

Query a Partial PostCode

$api = new Suilven\UKPostCodes\API();
$postcodeObjs = $this->api->query('SW16');

Get a Random Postcode

$api = new Suilven\UKPostCodes\API();
$random = $this->api->random();

Get Distance Between Two PostCodes

$api = new Suilven\UKPostCodes\API();
$distance = $this->api->distance('SW1A 2AB', 'EH99 1SP', Distance::KM);

If the distance units parameter is not provided, then the default is miles (MILES). The other option is NAUTICAL_MILES.

Check if a PostCode is Valid or Not

$api = new Suilven\UKPostCodes\API();

// false as there is no space in the postcode
$validated = $this->api->validate('KYAB92A');

Docker Dev Environment

Starting

Note that the first time this is executed the container will be built.

sudo docker-compose up -d phpcli

Getting A Bash Prompt

sudo docker-compose exec phpcli /bin/bash

Running Tests Locally

root@ukpostcodes.dev:/var/www> vendor/bin/phpunit tests/
PHPUnit 7.5.20 by Sebastian Bergmann and contributors.

..................................                                34 / 34 (100%)

Time: 156 ms, Memory: 6.00 MB

Generating Test Coverage

phpdbg -qrr vendor/bin/phpunit -d memory_limit=4G --coverage-html report   tests/