Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/boxuk/postcodes-io-bundle
A bundle for querying the postcodes.io web service.
https://github.com/boxuk/postcodes-io-bundle
Last synced: about 2 months ago
JSON representation
A bundle for querying the postcodes.io web service.
- Host: GitHub
- URL: https://github.com/boxuk/postcodes-io-bundle
- Owner: boxuk
- License: mit
- Created: 2014-08-18T10:21:47.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2021-10-18T15:56:05.000Z (about 3 years ago)
- Last Synced: 2024-10-12T21:50:35.132Z (3 months ago)
- Language: PHP
- Size: 16.6 KB
- Stars: 13
- Watchers: 44
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
PostcodesIoBundle
=================
[](https://travis-ci.org/boxuk/postcodes-io-bundle)
A bundle for querying the [postcodes.io](https://postcodes.io) web service.
[https://github.com/BoxUk/postcodes-io-bundle](https://github.com/BoxUk/postcodes-io-bundle)
[License](LICENSE)
Installation
------------
Installation is handled via [Composer](https://getcomposer.org).
1. Run the following command:
```bash
$ composer require boxuk/postcodes-io-bundle ~1.0
```
This should add the following to your project's `composer.json` file:
```js
"require": {
"boxuk/postcodes-io-bundle": "~1.0"
}
```
2. Add the bundle to your `app/AppKernel.php` file:
```php
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](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
-----
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
-------
lookup()
--------
[API documentation](https://postcodes.io/docs#Postcode-Lookup)
Lookup data about a particular postcode.
__Parameters:__
* `postcode` _(Required)_: The postcode.
__Example:__
```php
$response = $client->lookup(array('postcode' => 'CF10 1DD'));
```
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:__
```php
$response = $client->bulkLookup(array('postcodes' => array('CF10 1DD', 'W1B 4BD')));
```
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:__
```php
$response = $client->reverseGeocode(array('latitude' => 51.481667, 'longitude' => -3.182155));
```
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:__
```php
$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](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:__
```php
$response = $client->matching(array('query' => 'CF10', 'limit' => 20));
```
validate()
--------
[API documentation](https://postcodes.io/docs#Postcode-Validation)
Validate a postcode.
__Parameters:__
* `postcode` _(Required)_: The postcode to validate.
__Example:__
```php
$response = $client->validate(array('postcode' => 'CF10 1DD'));
```
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:__
```php
$response = $client->autocomplete(array('postcode' => 'CF10', 'limit' => 20));
```
random()
--------
[API documentation](https://postcodes.io/docs#Random-Postcode)
Get data for a random postcode.
__Parameters:__
None.
__Example:__
```php
$response = $client->random();
```
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:__
```php
$response = $client->outwardCodeLookup(array('outcode' => 'CF10'));
```