PostcodesIo

![Software License][ico-license], _(*1)

Description

A simple interface for querying the Postcodes.io UK postcode API using GuzzleHttp Version 6., _(*2)

Install

Via Composer, _(*3)

``` bash $ composer require PhilKershaw/postcodesio, _(*4)


## Usage

Simply import the `flashmatt\PostcodesIO\Client` class, create and instance and call any of the following methods:

``` php
use PhilKershaw\PostcodesIO\Client;

$client = new Client;

// Will return a whole host of information pertaining to the given post code.
$response = $client->postcodeLookup('W1A 1AA');

// Array containing postcodes.
$response = $client->bulkPostcodeLookup(['W1A 1AA', 'M50 2EQ']);

// Associative array containing latitude/longitude coordinates.
$response = $client->latLongLookup([
    'longitude' => 0.629834723775309,
    'latitude'  => 51.7923246977375
]);

// Nested associative arrays containing latitude/longitude coordinates and optional radius and limit.
// Radius will limit the range of the search and limit will, well, limit the number of results
// for a particular latitude/longitude lookup.
$response = $client->bulkLatLongLookup([
    [
        "longitude" => 0.629834723775309,
        "latitude"  => 51.7923246977375
    ],
    [
        "longitude" => -2.49690382054704,
        "latitude"  => 53.5351312861402,
        "radius"    => 1000,
        "limit"     => 5
    ]
]);

// Literally returns a random postcode.
$response = $client->getRandomPostcode();

$response = $client->validatePostcode('W1A 1AA');

// Will complete a partial postcode. Not tested thoroughly.
$response = $client->autocompletePostcode('W1A');

// Will return the nearest postcodes to a given post code.
$response = $client->getNearestPostcodes('W1A 1AA');

// Will perform an outcode lookup and return details specific to the outcode.
// NB The outcode refers to the first portion of the postcode.
// For example 'W1A' is the outcode in 'W1A 1AA'.
$response = $client->outcodeLookup('W1A');

// Similar to the nearest postcodes lookup but just for outcodes.
$response = $client->getNearestOutcodes('W1A');

// Similar to the straight lat/long lookup but just for outcodes.
$response = $client->outcodeLatLongLookup([
    'longitude' => 0.629834723775309,
    'latitude'  => 51.7923246977375
]);

All responses return an instance of GuzzleHttp\Psr7\Response which implements Psr\Http\Message\ResponseInterface. Therefore, you are able to fetch the status code simply by calling:, _(*5)

$response->getStatusCode();

and the headers:, _(*6)

$response->getHeaders();

a specific header:, _(*7)

$response->getHeader('Content-Type');

and the response body:, _(*8)

$response->getBody();

NB: The response from Postcodes.io typically takes the for of: ``` json, _(*9)

{ "status": 200, "result": {...} }, _(*10)

However, since the 'status' duplicates the HTTP response code `getBody()` will actually return just the 'result' allowing for example:

``` php
$postcode = json_decode($response->getBody())->postcode;
// OR
$latitude = json_decode($response->getBody())->latitude;

For further reading, checkout out the GuzzleHttp documentation as linked in the description., _(*11)