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)9125.3k—1.9%3[2 issues](https://github.com/jabranr/postcodes-io/issues)[2 PRs](https://github.com/jabranr/postcodes-io/pulls)1MITPHPPHP >= 7.3CI failing

Since Nov 25Pushed 5mo 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 yesterday

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

46

—

FairBetter than 92% of packages

Maintenance51

Moderate activity, may be stable

Popularity40

Moderate usage in the ecosystem

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

632d 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://avatars.githubusercontent.com/u/2131246?v=4)[Jabran Rafique](/maintainers/jabranr)[@jabranr](https://github.com/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.

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

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

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

Google Geocoding API for Laravel

50162.8k](/packages/jcf-geocode)[yajra/laravel-address

Philippines Address Lookup API for Laravel.

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

Teryt WS1 Api

1645.6k1](/packages/mrcnpdlk-teryt-api)[jackmartin/laravel-yandex-geocode

Simply service laravel Yandex Geocoding

1117.6k](/packages/jackmartin-laravel-yandex-geocode)

PHPackages © 2026

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