{"id":13828143,"url":"https://github.com/JustSteveKing/LaravelPostcodes","last_synced_at":"2025-07-09T05:31:42.723Z","repository":{"id":35163099,"uuid":"215026849","full_name":"JustSteveKing/LaravelPostcodes","owner":"JustSteveKing","description":"A service wrapper around postcodes.io","archived":false,"fork":false,"pushed_at":"2024-04-20T15:15:44.000Z","size":145,"stargazers_count":77,"open_issues_count":2,"forks_count":22,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-11T20:34:38.576Z","etag":null,"topics":["geolocation","hacktoberfest","laravel","laravel-package","php","postcodesio","validation"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JustSteveKing.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["JustSteveKing"]}},"created_at":"2019-10-14T11:33:14.000Z","updated_at":"2024-11-07T01:08:23.000Z","dependencies_parsed_at":"2024-06-19T10:00:05.262Z","dependency_job_id":null,"html_url":"https://github.com/JustSteveKing/LaravelPostcodes","commit_stats":{"total_commits":65,"total_committers":16,"mean_commits":4.0625,"dds":0.7076923076923076,"last_synced_commit":"912ab5df808e713dcf82c1e88dc07855dc25b92c"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JustSteveKing%2FLaravelPostcodes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JustSteveKing%2FLaravelPostcodes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JustSteveKing%2FLaravelPostcodes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JustSteveKing%2FLaravelPostcodes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JustSteveKing","download_url":"https://codeload.github.com/JustSteveKing/LaravelPostcodes/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225486548,"owners_count":17481924,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["geolocation","hacktoberfest","laravel","laravel-package","php","postcodesio","validation"],"created_at":"2024-08-04T09:02:34.074Z","updated_at":"2024-11-20T07:31:33.170Z","avatar_url":"https://github.com/JustSteveKing.png","language":"PHP","funding_links":["https://github.com/sponsors/JustSteveKing"],"categories":["PHP"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\n![](laravel-postal-code-validation.png)\n\n\u003c/p\u003e\n\n# LaravelPostcodes\n\n[![Latest Version on Packagist][ico-version]][link-packagist]\n[![Software License][ico-license]](LICENSE.md)\n[![Build Status][ico-github-action]][link-github-action]\n[![Coverage Status][ico-scrutinizer]][link-scrutinizer]\n[![Quality Score][ico-code-quality]][link-code-quality]\n[![Total Downloads][ico-downloads]][link-downloads]\n\nA service wrapper around [postcodes.io](https://postcodes.io/) with validation rule and macro\n\n## Install\n\nVia Composer\n\n```bash\n$ composer require juststeveking/laravel-postcodes\n```\n\nAfter installation, merge configuration for services using:\n\n```bash\n$ php artisan vendor:publish --provider=\"JustSteveKing\\LaravelPostcodes\\PostcodesServiceProvider\"\n```\n\nIf, for some reason, this doesn't work please use the following steps:\n\n- Add the following into the `config/services.php` configuration file:\n\n```php\n\u003c?php\n\n'postcodes' =\u003e [\n    'url' =\u003e env('POSTCODES_URL', 'https://api.postcodes.io/')\n],\n```\n\n- Add `POSTCODES_URL` to your `.env` file and add `https://api.postcodes.io/` as the value.\n\n\n## Basic Usage\n\nYou can use the validation rule:\n\n``` php\n\u003c?php\n\n$this-\u003evalidate($request, [\n    'postcode' =\u003e [\n        'required',\n        'string',\n        new Postcode(resolve(PostcodeService::class))\n    ]\n]);\n```\n\nOr you can use the validation Macro:\n\n```php\n$this-\u003evalidate($request, [\n    'postcode' =\u003e [\n        'required',\n        'string',\n        Rule::postcode()\n    ]\n]);\n```\n\nIf you want to interact with the service itself:\n\n```php\n\u003c?php \n\nuse JustSteveKing\\LaravelPostcodes\\Service\\PostcodeService;\n\nclass SomeController extends Controller\n{\n    protected $postcodes;\n\n    public function __construct(PostcodeService $service)\n    {\n        $this-\u003epostcodes = $service;\n    }\n\n    public function store(Request $request)\n    {\n        // validation using example above\n        $location = $this-\u003epostcodes-\u003egetPostcode($request-\u003epostcode);\n    }\n}\n```\n\nOr use the facade:\n\n```php\n\u003c?php \n\nclass SomeController extends Controller\n{\n    public function store(Request $request)\n    {\n        // validation using example above\n        $location = Postcode::getPostcode($request-\u003epostcode);\n    }\n}\n```\n\n### Validate\n\n```php\n\u003c?php\n\n$service = resolve(PostcodeService::class);\n\n$service-\u003evalidate('AB10 1AB');\n\n// You can also use the facade:\nPostcode::validate('AB10 1AB');\n```\n\n### Validate Postcode\n\n```php\n\u003c?php\n\n$service = resolve(PostcodeService::class);\n\n$service-\u003evalidate('AB10 1AB');\n\n// You can also use the facade:\nPostcode::validate('AB10 1AB');\n```\n\n### Get Postcode information\n\n```php\n\u003c?php\n\n$service = resolve(PostcodeService::class);\n\n$service-\u003egetPostcode('AB10 1AB');\n\n// You can also use the facade:\nPostcode::getPostcode('AB10 1AB');\n```\n\n\n### Bulk Lookup Postcodes\n\n```php\n\u003c?php\n\n$service = resolve(PostcodeService::class);\n\n$service-\u003egetPostcodes([\n    'AB10 1AB',\n    'AB10 1AF',\n    'AB10 1AG',\n]);\n\n// You can also use the facade:\nPostcode::getPostcodes([\n    'AB10 1AB',\n    'AB10 1AF',\n    'AB10 1AG',\n]);\n```\n\n### Get nearest postcodes for a given longitude \u0026 latitude\n\n```php\n\u003c?php\n\n$service = resolve(PostcodeService::class);\n\n$service-\u003enearestPostcodesForGivenLngAndLat(\n    0.629806,\n    51.792326\n);\n\n// You can also use the facade:\nPostcode::nearestPostcodesForGivenLngAndLat(\n    0.629806,\n    51.792326\n);\n```\n\n### Nearest postcodes for postcode\n\n```php\n\u003c?php\n\n$service = resolve(PostcodeService::class);\n\n$service-\u003enearest('AB10 1AB');\n\n// You can also use the facade:\nPostcode::nearest('AB10 1AB');\n```\n\n### Autocomplete a postcode partial\n\n```php\n\u003c?php\n\n$service = resolve(PostcodeService::class);\n\n$service-\u003eautocomplete('AB10');\n\n// You can also use the facade:\nPostcode::autocomplete('AB10');\n```\n\n### Query for postcode\n\n```php\n\u003c?php\n\n$service = resolve(PostcodeService::class);\n\n$service-\u003equery('AB10 1AB');\n\n// You can also use the facade:\nPostcode::query('AB10 1AB');\n```\n\n### Lookup terminated postcode\n\n```php\n\u003c?php\n\n$service = resolve(PostcodeService::class);\n\n$service-\u003egetTerminatedPostcode('AB1 0AA');\n\n// You can also use the facade:\nPostcode::getTerminatedPostcode('AB1 0AA');\n```\n\n### Lookup Outward Code\n\n```php\n\u003c?php\n\n$service = resolve(PostcodeService::class);\n\n$service-\u003egetOutwardCode('N11');\n\n// You can also use the facade:\nPostcode::getOutwardCode('N11');\n```\n\n### Nearest outward code for outward code\n\n```php\n\u003c?php\n\n$service = resolve(PostcodeService::class);\n\n$limit = 80; // Limit needs to be less than 100\n$radius = 15000; // Radius needs to be less than 25000\n$service-\u003egetNearestOutwardCode('N11', $limit, $radius);\n\n// You can also use the facade:\nPostcode::getNearestOutwardCode('N11', $limit, $radius);\n```\n\n### Get nearest outward codes for a given longitude \u0026 latitude\n\n```php\n\u003c?php\n\n$service = resolve(PostcodeService::class);\n\n$service-\u003enearestOutwardCodesForGivenLngAndLat(\n    0.629806,\n    51.792326\n);\n\n// You can also use the facade:\nPostcode::nearestOutwardCodesForGivenLngAndLat(\n    0.629806,\n    51.792326\n);\n```\n\n## Change log\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.\n\n## Testing\n\n``` bash\n$ composer test\n```\n\n## Contributing\n\nPlease see [CONTRIBUTING](CONTRIBUTING.md) and [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md) for details.\n\n## Security\n\nIf you discover any security related issues, please email juststevemcd@gmail.com instead of using the issue tracker.\n\n## Credits\n\n- [Steve McDougall][link-author]\n- [All Contributors][link-contributors]\n- [Laravel News for the artwork](https://www.laravel-news.com)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n\n[ico-version]: https://img.shields.io/packagist/v/juststeveking/laravel-postcodes.svg?style=flat-square\n[ico-license]: https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square\n[ico-github-action]: https://github.com/JustSteveKing/LaravelPostcodes/workflows/build-tests/badge.svg?branch=master\n[ico-scrutinizer]: https://img.shields.io/scrutinizer/coverage/g/JustSteveKing/LaravelPostcodes.svg?style=flat-square\n[ico-code-quality]: https://img.shields.io/scrutinizer/g/JustSteveKing/LaravelPostcodes.svg?style=flat-square\n[ico-downloads]: https://img.shields.io/packagist/dt/juststeveking/laravel-postcodes.svg?style=flat-square\n\n[link-packagist]: https://packagist.org/packages/juststeveking/laravel-postcodes\n[link-github-action]: https://github.com/JustSteveKing/LaravelPostcodes/actions\n[link-scrutinizer]: https://scrutinizer-ci.com/g/JustSteveKing/LaravelPostcodes/code-structure\n[link-code-quality]: https://scrutinizer-ci.com/g/JustSteveKing/LaravelPostcodes\n[link-downloads]: https://packagist.org/packages/juststeveking/laravel-postcodes\n[link-author]: https://github.com/JustSteveKing\n[link-contributors]: ../../contributors\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJustSteveKing%2FLaravelPostcodes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FJustSteveKing%2FLaravelPostcodes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJustSteveKing%2FLaravelPostcodes/lists"}