Postcodes for Laravel: GB Postcode Lookup and Geography Data

Postcodes for Laravel is Joshua Dovey's client for the GB Postcodes API. It returns typed objects for postcode lookups, geography, and proximity searches, with a Laravel validation rule and a fake for tests. If you have used the earlier Laravel wrapper for Postcodes.io , this package connects to a different postcode service and includes boundary and population data.

Look up postcodes and geography

The facade returns a Postcode object rather than an array. This example uses M16 0RA , the postcode for Manchester United's Old Trafford stadium. get() 回报 null for a postcode that does not resolve; getOrFail() throws a NotFoundException 。

使用

JoshDovey\Postcodes\Facades\Postcodes
;
$postcode
=

Postcodes
::
得到
（
'M16 0RA'
（英文）：
$postcode
？->
纬度
（）；
$postcode
？->
经度
（）；
$postcode
？->
地理
->
localAuthorityName;
$postcode
？->
地理
->
wardName;

The geography object includes administrative areas such as parliamentary constituencies, NHS integrated care boards, and police force areas. The package also exposes census and estimated population figures. For forms, autocomplete() returns a Laravel collection of matches for a partial postcode, while search() resolves multiple postcodes in batches of up to 100 per API request.

Validate a postcode against the dataset

拉拉维尔的 validation rules can use ValidPostcode to check whether a postcode exists, rather than only checking its format. unit() requires a full postcode such as M16 0RA 。

使用

JoshDovey\Postcodes\Rules\ValidPostcode
;
$请求
->
证实
（[

'postcode'

=>
[
'必需的'
,
ValidPostcode
::
单元
（）]，
]);

Values with an invalid shape fail locally, without an API request. By default, a format-valid value passes if the API check throws an error. To reject it instead, call (new ValidPostcode)->strict() or set postcodes.validation.strict 到 true in the published configuration.

Search by distance or boundary

For a delivery area or catchment, radius() finds postcodes near a given postcode. within() accepts a GeoJSON polygon, multipolygon, or feature. You can also calculate the distance between two postcodes, request a distance matrix, or reverse geocode coordinates.

$nearby
=

Postcodes
::
radius
（
'M16 0RA'
,
radius
:
2
,
限制
:
100
（英文）：
foreach
($nearby
作为
$result) {

回声
$结果
->
邮政编码
。
' '
。
$结果
->
distance;
}

Distance defaults to kilometres, with miles available per call or for the client. Lookups return boundary geometry by default; withoutBoundaries() 或 fields selection trims the response when you only need coordinates or names.

Install and test

The package requires PHP 8.2 or later and Laravel 12 or 13. Install it with Composer, then set the API key for the GB Postcodes API:

作曲家

要求

joshdovey/postcodes

POSTCODES_API_KEY
=your-key

Successful API responses are cached for one day by default. The client retries timeouts, connection failures, burst rate limits, and server errors twice by default. It does not retry an exhausted plan quota.

For tests, Postcodes::fake() replaces the client with stubbed responses and records requests:

使用

JoshDovey\Postcodes\Testing\Fixtures
;
$fake
=

Postcodes
::
伪造的
（[

'v1/postcodes/validate*'

=>

Fixtures
::
验证
（
'M16 0RA'
),
]);
$结果
=

Postcodes
::
证实
（
'M16 0RA'
（英文）：
$fake
->
断言已发送
（
'v1/postcodes/validate*'
（英文）：