LaravelPostcodes

A service wrapper around postcodes.io with validation rule and macro

Install

Via Composer

$ composer require juststeveking/laravel-postcodes

After installation, merge configuration for services using:

$ php artisan vendor:publish --provider="JustSteveKing\LaravelPostcodes\PostcodesServiceProvider"

If, for some reason, this doesn’t work please use the following steps:

Add the following into the config/services.php configuration file:

<?php

'postcodes' => [
    'url' => env('POSTCODES_URL', 'https://api.postcodes.io/')
],

Add POSTCODES_URL to your .env file and add https://api.postcodes.io/ as the value.

Basic Usage

You can use the validation rule:

<?php

$this->validate($request, [
    'postcode' => [
        'required',
        'string',
        new Postcode(resolve(PostcodeService::class))
    ]
]);

Or you can use the validation Macro:

$this->validate($request, [
    'postcode' => [
        'required',
        'string',
        Rule::postcode()
    ]
]);

If you want to interact with the service itself:

<?php

use JustSteveKing\LaravelPostcodes\Service\PostcodeService;

class SomeController extends Controller
{
    protected $postcodes;

    public function __construct(PostcodeService $service)
    {
        $this->postcodes = $service;
    }

    public function store(Request $request)
    {
        // validation using example above
        $location = $this->postcodes->getPostcode($request->postcode);
    }
}

Or use the facade:

<?php

class SomeController extends Controller
{
    public function store(Request $request)
    {
        // validation using example above
        $location = Postcode::getPostcode($request->postcode);
    }
}

Validate

<?php

$service = resolve(PostcodeService::class);

$service->validate('AB10 1AB');

// You can also use the facade:
Postcode::validate('AB10 1AB');

Validate Postcode

<?php

$service = resolve(PostcodeService::class);

$service->validate('AB10 1AB');

// You can also use the facade:
Postcode::validate('AB10 1AB');

Get Postcode information

<?php

$service = resolve(PostcodeService::class);

$service->getPostcode('AB10 1AB');

// You can also use the facade:
Postcode::getPostcode('AB10 1AB');

Bulk Lookup Postcodes

<?php

$service = resolve(PostcodeService::class);

$service->getPostcodes([
    'AB10 1AB',
    'AB10 1AF',
    'AB10 1AG',
]);

// You can also use the facade:
Postcode::getPostcodes([
    'AB10 1AB',
    'AB10 1AF',
    'AB10 1AG',
]);

Get nearest postcodes for a given longitude & latitude

<?php

$service = resolve(PostcodeService::class);

$service->nearestPostcodesForGivenLngAndLat(
    0.629806,
    51.792326
);

// You can also use the facade:
Postcode::nearestPostcodesForGivenLngAndLat(
    0.629806,
    51.792326
);

Nearest postcodes for postcode

<?php

$service = resolve(PostcodeService::class);

$service->nearest('AB10 1AB');

// You can also use the facade:
Postcode::nearest('AB10 1AB');

Autocomplete a postcode partial

<?php

$service = resolve(PostcodeService::class);

$service->autocomplete('AB10');

// You can also use the facade:
Postcode::autocomplete('AB10');

Query for postcode

<?php

$service = resolve(PostcodeService::class);

$service->query('AB10 1AB');

// You can also use the facade:
Postcode::query('AB10 1AB');

Lookup terminated postcode

<?php

$service = resolve(PostcodeService::class);

$service->getTerminatedPostcode('AB1 0AA');

// You can also use the facade:
Postcode::getTerminatedPostcode('AB1 0AA');

Lookup Outward Code

<?php

$service = resolve(PostcodeService::class);

$service->getOutwardCode('N11');

// You can also use the facade:
Postcode::getOutwardCode('N11');

Nearest outward code for outward code

<?php

$service = resolve(PostcodeService::class);

$limit = 80; // Limit needs to be less than 100
$radius = 15000; // Radius needs to be less than 25000
$service->getNearestOutwardCode('N11', $limit, $radius);

// You can also use the facade:
Postcode::getNearestOutwardCode('N11', $limit, $radius);

Get nearest outward codes for a given longitude & latitude

<?php

$service = resolve(PostcodeService::class);

$service->nearestOutwardCodesForGivenLngAndLat(
    0.629806,
    51.792326
);

// You can also use the facade:
Postcode::nearestOutwardCodesForGivenLngAndLat(
    0.629806,
    51.792326
);

Change log

Please see CHANGELOG for more information on what has changed recently.

Testing

$ composer test

Contributing

Please see CONTRIBUTING and CODE_OF_CONDUCT for details.

Security

If you discover any security related issues, please email juststevemcd@gmail.com instead of using the issue tracker.

Credits

License

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