PHPackages                             boxuk/postcodes-io-bundle - 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. [HTTP & Networking](/categories/http)
4. /
5. boxuk/postcodes-io-bundle

ActiveLibrary[HTTP & Networking](/categories/http)

boxuk/postcodes-io-bundle
=========================

A Symfony2 bundle for interaction with the postcodes.io service.

1.0.0(11y ago)134.7k4[1 PRs](https://github.com/boxuk/postcodes-io-bundle/pulls)MITPHPPHP >=5.4.0CI failing

Since Aug 18Pushed 4y ago42 watchersCompare

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

READMEChangelog (1)Dependencies (8)Versions (3)Used By (0)

PostcodesIoBundle
=================

[](#postcodesiobundle)

[![Build Status](https://camo.githubusercontent.com/3a2695ced02cbbcdbb1b9d646f890efd3584cb7e222043a97121fd0bd55b4cad/68747470733a2f2f7472617669732d63692e6f72672f626f78756b2f706f7374636f6465732d696f2d62756e646c652e737667)](https://travis-ci.org/boxuk/postcodes-io-bundle)

A bundle for querying the [postcodes.io](https://postcodes.io) web service.

[License](LICENSE)

Installation
------------

[](#installation)

Installation is handled via [Composer](https://getcomposer.org).

1. Run the following command:

    ```
    $ composer require boxuk/postcodes-io-bundle ~1.0
    ```

    This should add the following to your project's `composer.json` file:

    ```
    "require": {
        "boxuk/postcodes-io-bundle": "~1.0"
    }
    ```
2. Add the bundle to your `app/AppKernel.php` file:

    ```
    public function registerBundles()
    {
        $bundles = array(
            // ...
            new BoxUk\PostcodesIoBundle\BoxUkPostcodesIoBundle()
        );
    }
    ```

Services
--------

[](#services)

This bundle adds two services to your container:

- `box_uk_postcodes_io.client` A [GuzzleHttp\\Client](https://github.com/guzzle/guzzle-services) configured to query the postcodes.io service.
- `box_uk_postcodes_io.client_factory` A factory used to create instances of the client.

Usage
-----

[](#usage)

Inject the `box_uk_postcodes_io.client` service into your controller/class as you would any other service. Once you have the instance of the client, you can call the methods documented below on it, passing any parameters as an associative array.

The response will be a `GuzzleHttp\Command\Model` object, which you can access as an array, e.g. `echo $response['result']['latitude']`. Alternatively, you can just call `$response->toArray()` to get an array representation of the response. For further documentation on the structure of the response, please see [the postcodes.io documentation](https://postcodes.io/docs#Data).

Methods
-------

[](#methods)

lookup()
--------

[](#lookup)

[API documentation](https://postcodes.io/docs#Postcode-Lookup)

Lookup data about a particular postcode.

**Parameters:**

- `postcode` *(Required)*: The postcode.

**Example:**

```
$response = $client->lookup(array('postcode' => 'CF10 1DD'));
```

bulkLookup()
------------

[](#bulklookup)

[API documentation](https://postcodes.io/docs#Bulk-Postcode-Lookup)

Lookup data about a set of postcodes.

**Parameters:**

- `postcodes` *(Required)*: An array of postcodes (max 100).

**Example:**

```
$response = $client->bulkLookup(array('postcodes' => array('CF10 1DD', 'W1B 4BD')));
```

reverseGeocode()
----------------

[](#reversegeocode)

[API documentation](https://postcodes.io/docs#Geocode-Postcode)

Get data for postcodes nearest a given latitude/longitude coordinate.

**Parameters:**

- `latitude` *(Required)*: The latitude.
- `longitude` *(Required)*: The longitude.
- `limit` *(Optional)*: The maximum number of postcodes to return (default 10, max 100).
- `radius` *(Optional)*: The radius in metres in which to find postcodes (default 100, max 1000).

**Example:**

```
$response = $client->reverseGeocode(array('latitude' => 51.481667, 'longitude' => -3.182155));
```

bulkReverseGeocode()
--------------------

[](#bulkreversegeocode)

[API documentation](https://postcodes.io/docs#Geocode-Postcode)

Bulk translation of latitude/longitude coordinates into postcode data.

**Parameters:**

- `geolocations` *(Required)*: The geolocations to look up (maximum 100). This parameter should be an array, each element with the following keys:

    - `latitude` *(Required)*: The latitude.
    - `longitude` *(Required)*: The longitude.
    - `limit` *(Optional)*: The maximum number of postcodes to return (default 10, max 100).
    - `radius` *(Optional)*: The radius in metres in which to find postcodes (default 100, max 1000).

**Example:**

```
$response = $client->bulkReverseGeocode(
    array(
        'geolocations' => array(
            array('latitude' => 51.481667, 'longitude' => -3.182155),
            array('latitude' => 51.88328, 'longitude' => -3.43684, 'limit' => 5, 'radius' => 500)
        )
    )
);
```

matching()
----------

[](#matching)

[API documentation](https://postcodes.io/docs#Postcode-Query)

Find postcodes matching a given query.

**Parameters:**

- `query` *(Optional)*: The postcode query, e.g. 'CF10'.
- `limit` *(Optional)*: The maximum number of postcodes to return (default 10, max 100).

**Example:**

```
$response = $client->matching(array('query' => 'CF10', 'limit' => 20));
```

validate()
----------

[](#validate)

[API documentation](https://postcodes.io/docs#Postcode-Validation)

Validate a postcode.

**Parameters:**

- `postcode` *(Required)*: The postcode to validate.

**Example:**

```
$response = $client->validate(array('postcode' => 'CF10 1DD'));
```

autocomplete()
--------------

[](#autocomplete)

[API documentation](https://postcodes.io/docs#Postcode-Autocomplete)

Get a list of postcodes to autocomplete a partial postcode.

**Parameters:**

- `postcode` *(Required)*: The postcode to autocomplete.
- `limit` *(Optional)*: The maximum number of postcodes to return (default 10, max 100).

**Example:**

```
$response = $client->autocomplete(array('postcode' => 'CF10', 'limit' => 20));
```

random()
--------

[](#random)

[API documentation](https://postcodes.io/docs#Random-Postcode)

Get data for a random postcode.

**Parameters:**None.

**Example:**

```
$response = $client->random();
```

outwardCodeLookup()
-------------------

[](#outwardcodelookup)

[API documentation](https://postcodes.io/docs#Show-Outcode)

Get data for the specified "outward code" (first half of postcode).

**Parameters:**

- `outcode` *(Required)*: The outward code (first half of postcode) to get location data for.

**Example:**

```
$response = $client->outwardCodeLookup(array('outcode' => 'CF10'));
```

###  Health Score

35

—

LowBetter than 80% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity31

Limited adoption so far

Community20

Small or concentrated contributor base

Maturity59

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 53.3% 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

Unknown

Total

1

Last Release

4291d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/3c8c170d78af034f9aee1c84e279b97e5b61b549ce8b8519ed8da81402ac8e96?d=identicon)[BoxUK](/maintainers/BoxUK)

---

Top Contributors

[![chriscollinsboxuk](https://avatars.githubusercontent.com/u/783292?v=4)](https://github.com/chriscollinsboxuk "chriscollinsboxuk (8 commits)")[![studioromeo](https://avatars.githubusercontent.com/u/846587?v=4)](https://github.com/studioromeo "studioromeo (3 commits)")[![jenkoian](https://avatars.githubusercontent.com/u/131355?v=4)](https://github.com/jenkoian "jenkoian (2 commits)")[![aaronahearne](https://avatars.githubusercontent.com/u/5104743?v=4)](https://github.com/aaronahearne "aaronahearne (1 commits)")[![rjwaring](https://avatars.githubusercontent.com/u/3215392?v=4)](https://github.com/rjwaring "rjwaring (1 commits)")

---

Tags

Guzzlepostcodepostcodes.io

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

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

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

###  Alternatives

[eightpoints/guzzle-bundle

Integrates Guzzle 6.x, a PHP HTTP Client, into Symfony. Comes with easy and powerful configuration options and optional plugins.

45912.1M55](/packages/eightpoints-guzzle-bundle)[ajt/guzzle-toggl

Toggl API client written on top of Guzzle PHP.

8826.2k2](/packages/ajt-guzzle-toggl)[loco/swizzle

Build Guzzle service descriptions from Swagger compliant APIs

279.7k2](/packages/loco-swizzle)[facile-it/crossbar-http-publisher-bundle

This bundle allows to submit PubSub events via HTTP/POST requests to a Crossbar HTTP Publisher.

1114.4k](/packages/facile-it-crossbar-http-publisher-bundle)

PHPackages © 2026

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