PostcodesIoBundle

A bundle for querying the postcodes.io web service.

https://github.com/BoxUk/postcodes-io-bundle

License

Installation

Installation is handled via Composer.

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

This bundle adds two services to your container:

• box_uk_postcodes_io.client A GuzzleHttp\Client configured to query the postcodes.io service.
• box_uk_postcodes_io.client_factory A factory used to create instances of the client.

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.

Methods

lookup()

API documentation

Lookup data about a particular postcode.

Parameters:

• postcode (Required): The postcode.

Example:

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

bulkLookup()

API documentation

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()

API documentation

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()

API documentation

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()

API documentation

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()

API documentation

Validate a postcode.

Parameters:

• postcode (Required): The postcode to validate.

Example:

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

autocomplete()

API documentation

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()

API documentation

Get data for a random postcode.

Parameters: None.

Example:

$response = $client->random();

outwardCodeLookup()

API documentation

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'));