suilven/ukpostcodes

Wrapper around postcodes.io to get info about UK postcodes

1.0.0 2020-05-10 22:06 UTC

Requires

• php-vcr/php-vcr: ^1.4
• php-vcr/phpunit-testlistener-vcr: dev-master

Requires (Dev)

• clue/graph-composer: dev-master
• ergebnis/composer-normalize: dev-master
• phpstan/phpstan: ^0.12.0@dev
• phpunit/phpunit: ^7.5
• squizlabs/php_codesniffer: ^3.0@dev
• vimeo/psalm: ^3.0@dev

MIT

• Gordon Anderson

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

[e-mail]:/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/