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

ammaar23 / postcodes-io-sdk

Maintainers

Details