README

A simple PHP sdk for Postcodes.io

Install

Install using composer:

$ composer require ammaar23/postcodes-io-sdk

Documentation

Basic Usage Example

use Ammaar23\Postcodes\Postcode;
use Ammaar23\Postcodes\PostcodeException;

try {
    $postcodeService = new Postcode();
    $response = $postcodeService->lookup('M60 2LA');
    echo $response->admin_district;
} catch(PostcodeException $e) {
    echo $e->getMessage();
} catch(\Exception $e) {
    echo $e->getMessage();
}

You can catch specific Ammaar23\Postcodes\PostcodeException and/or catch general \Exception to catch any type.

Add/Modify Configuration Parameters

You can look at Guzzle HTTP Request Options to find out the availabe options.

$postcodeService = new Postcode([
    'headers' => [
        'User-Agent' => 'testing/1.0',
        'Accept' => 'application/json'
    ],
    'timeout' => 2.0
]);

Methods

Lookup a postcode

Returns a single postcode entity for a given postcode (case, space insensitive).

// Definition
function lookup(string $postcode): stdClass;

// Example
$postcodeService->lookup('M60 2LA');

Bulk lookup postcodes

Returns a list of matching postcodes and respective available data.

// Definition
function lookupBulk(array $postcodes, array $attributes = []): array;

// Examples
$postcodeService->lookupBulk(['OX49 5NU', 'NE30 1DP']);
$postcodeService->lookupBulk(
    ['OX49 5NU', 'NE30 1DP'],
    ['postcode', 'longitude', 'latitude']
);

• $attributes (not required) is an array attributes to be returned in the result object(s).

Reverse Geocoding

Returns nearest postcodes for a given longitude and latitude.

// Definition
function reverseGeocode(float $latitude, float $longitude, array $options = []): array;

// Examples
$postcodeService->reverseGeocode(51.7923246977375, 0.629834723775309);
$postcodeService->reverseGeocode(51.7923246977375, 0.629834723775309, [
    'limit' => 5,
    'radius' => 1000
]);

• limit (not required) Limits number of postcodes matches to return. Defaults to 10. Needs to be less than 100.
• radius (not required) Limits number of postcodes matches to return. Defaults to 100m. Needs to be less than 2,000m.

Bulk Reverse Geocoding

Bulk translates geolocations into Postcodes.

// Definition
function reverseGeocodeBulk(array $geolocations, array $attributes = [], int $wideSearch = null): array;

// Examples
$postcodeService->reverseGeocodeBulk([
    ['latitude' => 51.7923246977375, 'longitude' => 0.629834723775309],
    ['latitude' => 53.5351312861402, 'longitude' => -2.49690382054704, 'radius' => 1000, 'limit' => 5]
]);
$postcodeService->reverseGeocodeBulk([
    ['latitude' => 51.7923246977375, 'longitude' => 0.629834723775309],
    ['latitude' => 53.5351312861402, 'longitude' => -2.49690382054704, 'radius' => 1000, 'limit' => 5]
], ['postcode', 'longitude', 'latitude']);
$postcodeService->reverseGeocodeBulk([
    ['latitude' => 51.7923246977375, 'longitude' => 0.629834723775309],
    ['latitude' => 53.5351312861402, 'longitude' => -2.49690382054704, 'radius' => 1000, 'limit' => 5]
], ['postcode', 'longitude', 'latitude'], 1000);

• Maximum of 100 geolocations per request.
• $attributes (not required) is an array attributes to be returned in the result object(s).
• $wideSearch (not required) Search up to 20km radius, but subject to a maximum of 10 results.

Random Postcode

Returns a random postcode and all available data for that postcode.

// Definition
function random(array $options = []): stdClass;

// Examples
$postcodeService->random();
$postcodeService->random([
    'outcode' => 'M60'
]);

• outcode (not required) Filters random postcodes by outcode. Returns null if invalid outcode.

Validate a postcode

Convenience method to validate a postcode.

// Definition
function validate(string $postcode): bool;

// Example
$postcodeService->validate('M60 2LA');

Validate a postcode format

Convenience method to validate a postcode format.

// Definition
function validateFormat(string $postcode): bool;

// Example
$postcodeService->validateFormat('M60 2LA');

validateFormat validates the format only where as validate check's if it exists in the Postcodes.io database or not.

Nearest postcodes for postcode

Returns nearest postcodes for a given postcode.

// Definition
function nearest(string $postcode, array $options = []): array;

// Examples
$postcodeService->nearest('M60 2LA');
$postcodeService->nearest('M60 2LA', [
    'limit' => 5,
    'radius' => 1000
]);

• limit (not required) Limits number of postcodes matches to return. Defaults to 10. Needs to be less than 100.
• radius (not required) Limits number of postcodes matches to return. Defaults to 100m. Needs to be less than 2,000m.

Autocomplete a postcode partial

Convenience method to return an list of matching postcodes.

// Definition
function autocomplete(string $postcode, array $options = []): array;

// Examples
$postcodeService->autocomplete('M60');
$postcodeService->autocomplete('M60', ['limit' => 5]);

• limit (not required) Limits number of postcodes matches to return. Defaults to 10. Needs to be less than 100.

Query for postcode

Submit a postcode query and receive a complete list of postcode matches and all associated postcode data. The result set can either be empty or populated with up to 100 postcode entities.

// Definition
function query(string $query, array $options = []): array|null;

// Examples
$postcodeService->query('M60 2LA');
$postcodeService->query('M60 2LA', ['limit' => 5]);

• limit (not required) Limits number of postcodes matches to return. Defaults to 10. Needs to be less than 100.

Testing

$ composer test

OR with coverage:

$ composer test-coverage

License

MIT License © 2019 – Ammaar Latif