PostcodesIo

Description

A simple interface for querying the Postcodes.io UK postcode API using GuzzleHttp Version 6.

Install

Via Composer

$ composer require PhilKershaw/postcodesio

Usage

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

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:

$response->getStatusCode();

and the headers:

$response->getHeaders();

a specific header:

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

and the response body:

$response->getBody();

NB: The response from Postcodes.io typically takes the for of:

{
    "status": 200,
    "result": {...}
}

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

$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.

License

The MIT License (MIT). Please see License File for more information.