Postcodes for Laravel: GB Postcode Lookup Package | Mohamed Said [ ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed Said Laravel Backend Engineer ](https://www.msaied.com) [ Home ](https://www.msaied.com) [ Projects ](https://www.msaied.com/projects) [ Articles ](https://www.msaied.com/articles) [ Certificates ](https://www.msaied.com/certificates) [ Contact ](https://www.msaied.com#contact-section) [ ](https://github.com/EG-Mohamed) [ Home ](https://www.msaied.com) [ Projects ](https://www.msaied.com/projects) [ Articles ](https://www.msaied.com/articles) [ Certificates ](https://www.msaied.com/certificates) [ Contact ](https://www.msaied.com#contact-section) [ home ](https://www.msaied.com) [ articles ](https://www.msaied.com/articles) Postcodes for Laravel: GB Postcode Lookup and Geography Data On this page 1. [ What Is Postcodes for Laravel? ](#what-is-postcodes-for-laravel) 2. [ Installation ](#installation) 3. [ Looking Up a Postcode ](#looking-up-a-postcode) 4. [ Validating a Postcode in a Form ](#validating-a-postcode-in-a-form) 5. [ Proximity and Boundary Searches ](#proximity-and-boundary-searches) 6. [ Testing with Fakes ](#testing-with-fakes) 7. [ Key Takeaways ](#key-takeaways) ![Postcodes for Laravel: GB Postcode Lookup and Geography Data](https://cdn.msaied.com/730/d8f9ca2085c0f6cc42cc82368bce275a.png) [ Laravel ](https://www.msaied.com/articles?category=laravel) [ Composer Pacakge ](https://www.msaied.com/articles?category=composer-pacakge) #Laravel #PHP #Composer Package #Postcode #GB Postcodes #Geolocation Postcodes for Laravel: GB Postcode Lookup and Geography Data ============================================================== 1 Oct 2026 3 min read ![Mohamed Said](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) Mohamed Said Table of contents 1. [ 01 What Is Postcodes for Laravel? ](#what-is-postcodes-for-laravel) 2. [ 02 Installation ](#installation) 3. [ 03 Looking Up a Postcode ](#looking-up-a-postcode) 4. [ 04 Validating a Postcode in a Form ](#validating-a-postcode-in-a-form) 5. [ 05 Proximity and Boundary Searches ](#proximity-and-boundary-searches) 6. [ 06 Testing with Fakes ](#testing-with-fakes) 7. [ 07 Key Takeaways ](#key-takeaways) What Is Postcodes for Laravel? ------------------------------ [Postcodes for Laravel](https://github.com/Josh-Dovey/postcodes-laravel) is Joshua Dovey's Composer package that wraps the GB Postcodes API. Unlike earlier Postcodes.io wrappers, this client returns **typed objects** rather than plain arrays and bundles boundary geometry, census figures, and estimated population data alongside the standard coordinate and administrative fields. The package requires **PHP 8.2+** and **Laravel 12 or 13**. Installation ------------ ```bash composer require joshdovey/postcodes ``` Add your API key to `.env`: ```env POSTCODES_API_KEY=your-key ``` Successful responses are cached for one day by default. The client retries on timeouts, connection failures, burst rate limits, and server errors (twice by default), but will not retry an exhausted plan quota. Looking Up a Postcode --------------------- The `Postcodes` facade returns a `Postcode` object. `get()` returns `null` when a postcode cannot be resolved; `getOrFail()` throws a `NotFoundException`. ```php use JoshDovey\Postcodes\Facades\Postcodes; $postcode = Postcodes::get('M16 0RA'); $postcode?->latitude(); $postcode?->longitude(); $postcode?->geography->localAuthorityName; $postcode?->geography->wardName; ``` The `geography` object includes parliamentary constituencies, NHS integrated care boards, police force areas, and more. `autocomplete()` returns a Laravel collection of matches for a partial postcode string, and `search()` resolves up to 100 postcodes in a single batched API request. Validating a Postcode in a Form ------------------------------- `ValidPostcode::unit()` checks whether a full postcode actually exists in the dataset, not just whether its format is correct. ```php use JoshDovey\Postcodes\Rules\ValidPostcode; $request->validate([ 'postcode' => ['required', ValidPostcode::unit()], ]); ``` Values with an invalid shape fail locally without hitting the API. By default, a format-valid postcode passes if the API call throws an error. To reject it in that scenario, call `(new ValidPostcode)->strict()` or set `postcodes.validation.strict` to `true` in the published config. Proximity and Boundary Searches ------------------------------- `radius()` finds postcodes within a given distance of a starting postcode. Distance defaults to kilometres; miles are available per call or globally via the client config. ```php $nearby = Postcodes::radius('M16 0RA', radius: 2, limit: 100); foreach ($nearby as $result) { echo $result->postcode . ' ' . $result->distance; } ``` `within()` accepts a GeoJSON polygon, multipolygon, or feature for catchment-style queries. Additional methods cover distance between two postcodes, distance matrices, and reverse geocoding. Boundary geometry is included in responses by default; call `withoutBoundaries()` or pass a `fields` selection to trim the payload when you only need coordinates or names. Testing with Fakes ------------------ `Postcodes::fake()` replaces the HTTP client with stubbed responses and records every request, making assertions straightforward. ```php use JoshDovey\Postcodes\Testing\Fixtures; $fake = Postcodes::fake([ 'v1/postcodes/validate*' => Fixtures::validation('M16 0RA'), ]); $result = Postcodes::validate('M16 0RA'); $fake->assertSent('v1/postcodes/validate*'); ``` Key Takeaways ------------- - Returns typed `Postcode` objects with geography, boundary, and population data. - `ValidPostcode::unit()` validates existence against the live dataset, not just format. - `radius()` and `within()` handle delivery-area and catchment queries out of the box. - Responses are cached for one day; the client retries transient failures automatically. - `Postcodes::fake()` provides first-class test support with fixture stubs and request assertions. - Requires PHP 8.2+ and Laravel 12 or 13. --- *Source: [Laravel News — Postcodes for Laravel](https://laravel-news.com/postcodes-for-laravel)* Found this useful? [ ](https://twitter.com/intent/tweet?url=https%3A%2F%2Fwww.msaied.com%2Farticles%2Fpostcodes-for-laravel-gb-postcode-lookup-and-geography-data&text=Postcodes+for+Laravel%3A+GB+Postcode+Lookup+and+Geography+Data) [ ](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fwww.msaied.com%2Farticles%2Fpostcodes-for-laravel-gb-postcode-lookup-and-geography-data) Frequently Asked Questions ---------------------------- 3 questions Q01 What is the difference between Postcodes for Laravel and the older Laravel Postcodes.io wrapper? Postcodes for Laravel connects to the GB Postcodes API (a different service from Postcodes.io) and returns typed objects instead of plain arrays. It also includes boundary geometry, census data, and estimated population figures that the Postcodes.io wrapper does not provide. Q02 How does the ValidPostcode rule differ from a simple regex format check? ValidPostcode::unit() makes a live API call to confirm the postcode actually exists in the dataset, not just that it matches the expected format. Values with an invalid shape are rejected locally without an API request. You can enable strict mode to also reject format-valid postcodes when the API call fails. Q03 How can I test code that uses the Postcodes facade without making real API calls? Call Postcodes::fake() with a map of URL patterns to fixture responses. The fake client records every request so you can assert which endpoints were called using $fake->assertSent(). Continue reading More Articles --------------- [ View all ](https://www.msaied.com/articles) [ ![Eloquent Custom Relations: Polymorphic Pivots, Has-One-Of-Many, and Raw Join Relations](https://cdn.msaied.com/728/b96439f5ef5f084b44d736951875f964.png) laravel eloquent database ### Eloquent Custom Relations: Polymorphic Pivots, Has-One-Of-Many, and Raw Join Relations Beyond belongsTo and hasMany lies a set of underused Eloquent relation types that eliminate ugly query hacks.... ![Mohamed Said](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) Mohamed Said 2 Oct 2026 3 min read Read ](https://www.msaied.com/articles/eloquent-custom-relations-polymorphic-pivots-has-one-of-many-and-raw-join-relations) [ ![Laravel Caching Strategies: Tags, Stampede Prevention, and Cache-Aside at Scale](https://cdn.msaied.com/727/7873d7495db459e7a6e3bfbb8835852d.png) laravel caching redis ### Laravel Caching Strategies: Tags, Stampede Prevention, and Cache-Aside at Scale Beyond simple remember() calls: how to use cache tags for granular invalidation, prevent thundering-herd stamp... ![Mohamed Said](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) Mohamed Said 2 Oct 2026 3 min read Read ](https://www.msaied.com/articles/laravel-caching-strategies-tags-stampede-prevention-and-cache-aside-at-scale-2) [ ![WhenMounted and BigInt Props in Inertia.js v3.8](https://cdn.msaied.com/729/4eab9f8b1fbacb1b12abdbafcf28331f.png) Inertia.js Laravel SSR ### WhenMounted and BigInt Props in Inertia.js v3.8 Inertia.js v3.8.0 ships a WhenMounted component for SSR-safe browser-only rendering, native BigInt support for... ![Mohamed Said](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) Mohamed Said 2 Oct 2026 3 min read Read ](https://www.msaied.com/articles/whenmounted-and-bigint-props-in-inertiajs-v38) [ ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed Said Laravel Backend Engineer ](https://www.msaied.com)Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow. Explore - [Home](https://www.msaied.com) - [Projects](https://www.msaied.com/projects) - [Articles](https://www.msaied.com/articles) - [Certificates](https://www.msaied.com/certificates) - [Contact](https://www.msaied.com#contact-section) Connect - [ hello@msaied.com ](mailto:hello@msaied.com) - [ +20 109 461 9204 ](tel:+201094619204) © 2026 Mohamed Said. All rights reserved. [ ](https://github.com/EG-Mohamed) [ ](https://www.linkedin.com/in/msaiedm/) [ ](https://wa.me/201094619204) [ ](mailto:hello@msaied.com) [ ](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view)