PHPackages                             jabranr/postcodes-io - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. jabranr/postcodes-io

ActiveLibrary[API Development](/categories/api)

jabranr/postcodes-io
====================

PHP library for postcodes.io API

2.0.1(1y ago)9113.6k↓18.4%3[2 issues](https://github.com/jabranr/postcodes-io/issues)[2 PRs](https://github.com/jabranr/postcodes-io/pulls)1MITPHPPHP >= 7.3CI passing

Since Nov 25Pushed 3mo ago1 watchersCompare

[ Source](https://github.com/jabranr/postcodes-io)[ Packagist](https://packagist.org/packages/jabranr/postcodes-io)[ RSS](/packages/jabranr-postcodes-io/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (3)Dependencies (1)Versions (9)Used By (1)

PostcodesIO [![Tests](https://github.com/jabranr/postcodes-io/actions/workflows/phpunit-tests.yml/badge.svg)](https://github.com/jabranr/postcodes-io/actions/workflows/phpunit-tests.yml) [![Packagist Version](https://camo.githubusercontent.com/eef9f976020b21a8924102d4b30622f4a960d0ccb2baabb8ad9fbad124ad590c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6a616272616e722f706f7374636f6465732d696f3f7374796c653d666c61742d737175617265)](https://camo.githubusercontent.com/eef9f976020b21a8924102d4b30622f4a960d0ccb2baabb8ad9fbad124ad590c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6a616272616e722f706f7374636f6465732d696f3f7374796c653d666c61742d737175617265) [![Packagist PHP Version Support](https://camo.githubusercontent.com/8656d8db06d590168e2a516d7262c88c10eb9c81e9dda6b1c6d00352d9575ae6/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6a616272616e722f706f7374636f6465732d696f3f7374796c653d666c61742d737175617265)](https://camo.githubusercontent.com/8656d8db06d590168e2a516d7262c88c10eb9c81e9dda6b1c6d00352d9575ae6/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6a616272616e722f706f7374636f6465732d696f3f7374796c653d666c61742d737175617265)
====================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================

[](#postcodesio---)

PostcodesIO is a PHP library for postcodes.io API.

Install
=======

[](#install)

Install using composer:

```
$ composer require jabranr/postcodes-io

```

Documentation
=============

[](#documentation)

All of the following methods return back the same [complete response](https://postcodes.io/docs) as it comes from postcodes.io API in JSON format.

Development
===========

[](#development)

**Prerequisites**

- Docker
- Start container: `docker-compose up`
- Run tests: `docker-compose exec postcodes_io bash -c "composer test"`

**Debugging**Xdebug is already installed and enabled as part of the docker setup. The project includes `launch.json` debug setup file for VSCode.

#### Find postcode information

[](#find-postcode-information)

```
use Jabranr\PostcodesIO\PostcodesIO;

$postcodesIO = new PostcodesIO();

try {
  $addresses = $postcodesIO->find('NW1 5LD');
} catch(\Exception $e) {
  echo $e->getMessage();
}
```

> You can catch specific `Jabranr\PostcodesIO\Exception\PostcodeIOException` or/and catch general `\Exception` to catch any type.

```
use Jabranr\PostcodesIO\PostcodesIO;

$postcodesIO = new PostcodesIO('NW1 5LD');
$addresses = $postcodesIO->getResult();
```

#### Find postcode information by geo location

[](#find-postcode-information-by-geo-location)

```
use Jabranr\PostcodesIO\PostcodesIO;

$postcodesIO = new PostcodesIO();
$addresses = $postcodesIO->findByLocation(51.520331, -0.1396267);
```

#### Find random postcode information

[](#find-random-postcode-information)

```
use Jabranr\PostcodesIO\PostcodesIO;

$postcodesIO = new PostcodesIO();
$addresses = $postcodesIO->findRandom();
```

OR use the alias method:

```
use Jabranr\PostcodesIO\PostcodesIO;

$postcodesIO = new PostcodesIO();
$addresses = $postcodesIO->random();
```

#### Validate a postcode

[](#validate-a-postcode)

```
use Jabranr\PostcodesIO\PostcodesIO;

$postcodesIO = new PostcodesIO();
$addresses = $postcodesIO->validate('NW1 5LD');
```

#### Find nearest postcodes

[](#find-nearest-postcodes)

```
use Jabranr\PostcodesIO\PostcodesIO;

$postcodesIO = new PostcodesIO();
$addresses = $postcodesIO->findNearest('NW1 5LD');
```

OR use the alias method:

```
use Jabranr\PostcodesIO\PostcodesIO;

$postcodesIO = new PostcodesIO();
$addresses = $postcodesIO->nearest();
```

#### Get an autocompleted list of a postcode/outcode

[](#get-an-autocompleted-list-of-a-postcodeoutcode)

```
use Jabranr\PostcodesIO\PostcodesIO;

$postcodesIO = new PostcodesIO();
$addresses = $postcodesIO->autocomplete('NW1');
```

#### Search a postcode

[](#search-a-postcode)

```
use Jabranr\PostcodesIO\PostcodesIO;

$postcodesIO = new PostcodesIO();
$addresses = $postcodesIO->query('NW1 5LD');
```

OR use the alias method:

```
use Jabranr\PostcodesIO\PostcodesIO;

$postcodesIO = new PostcodesIO();
$addresses = $postcodesIO->search('NW1 5LD');
```

#### Find an outcode

[](#find-an-outcode)

```
use Jabranr\PostcodesIO\PostcodesIO;

$postcodesIO = new PostcodesIO();
$addresses = $postcodesIO->findOutcode('NW1');
```

#### Find nearest outcodes

[](#find-nearest-outcodes)

```
use Jabranr\PostcodesIO\PostcodesIO;

$postcodesIO = new PostcodesIO();
$addresses = $postcodesIO->nearestOutcode('NW1');
```

#### Find an outcode by location

[](#find-an-outcode-by-location)

```
use Jabranr\PostcodesIO\PostcodesIO;

$postcodesIO = new PostcodesIO();
$addresses = $postcodesIO->findOutcodeByLocation(51.520331, -0.1396267);
```

#### Bulk postcodes search

[](#bulk-postcodes-search)

```
use Jabranr\PostcodesIO\PostcodesIO;

$postcodesIO = new PostcodesIO();
$addresses = $postcodesIO->bulkPostcodeSearch(array('NW1 5LD', 'W1T 7NY'));
```

> Maximum of 100 postcodes per request.

#### Bulk reverse geocoding

[](#bulk-reverse-geocoding)

```
use Jabranr\PostcodesIO\PostcodesIO;

$postcodesIO = new PostcodesIO();
$addresses = $postcodesIO->bulkReverseGeocoding(array(
    array(51.520331, -0.1396267),
    array(51.520331, -0.1396267)
));
```

or

```
use Jabranr\PostcodesIO\PostcodesIO;

$postcodesIO = new PostcodesIO();
$addresses = $postcodesIO->bulkReverseGeocoding(array(
    array('latitude' => 51.520331, 'longitude' => -0.1396267),
    array('latitude' => 51.520331, 'longitude' => -0.1396267)
));
```

> Maximum of 100 geolocations per request.

License
=======

[](#license)

MIT License © 2016 – present | Jabran Rafique

###  Health Score

47

—

FairBetter than 94% of packages

Maintenance56

Moderate activity, may be stable

Popularity39

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity63

Established project with proven stability

 Bus Factor1

Top contributor holds 88.2% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~718 days

Total

5

Last Release

586d ago

Major Versions

0.0.1 → 1.0.02016-11-26

1.0.1 → 2.0.02022-10-09

PHP version history (2 changes)0.0.1PHP >= 5.3.0

2.0.0PHP >= 7.3

### Community

Maintainers

![](https://www.gravatar.com/avatar/bac8f15aa523ecd5653b9eee1649ca5f00c562f2b0f84a595d58d79e409aec66?d=identicon)[jabranr](/maintainers/jabranr)

---

Top Contributors

[![jabranr](https://avatars.githubusercontent.com/u/2131246?v=4)](https://github.com/jabranr "jabranr (15 commits)")[![jamieburchell](https://avatars.githubusercontent.com/u/3270426?v=4)](https://github.com/jamieburchell "jamieburchell (2 commits)")

---

Tags

apioutcodephp-librarypostcodeaddresspostcodeuk

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/jabranr-postcodes-io/health.svg)

```
[![Health](https://phpackages.com/badges/jabranr-postcodes-io/health.svg)](https://phpackages.com/packages/jabranr-postcodes-io)
```

###  Alternatives

[shippo/shippo-php

A PHP library for connecting with multiple carriers (FedEx, UPS, USPS) using Shippo.

1711.8M2](/packages/shippo-shippo-php)[nickurt/laravel-postcodeapi

Universal PostcodeApi for Laravel 11.x/12.x/13.x

97221.2k](/packages/nickurt-laravel-postcodeapi)[jcf/geocode

Google Geocoding API for Laravel

48160.5k](/packages/jcf-geocode)[freshheads/postcode-api-client

Client library for the postcodeapi.nu web service.

16125.5k](/packages/freshheads-postcode-api-client)[yajra/laravel-address

Philippines Address Lookup API for Laravel.

4015.8k](/packages/yajra-laravel-address)[mrcnpdlk/teryt-api

Teryt WS1 Api

1640.6k1](/packages/mrcnpdlk-teryt-api)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)