Giter Club home page Giter Club logo

postcodes-io's Introduction

PostcodesIO Tests Packagist Version Packagist PHP Version Support

PostcodesIO is a PHP library for postcodes.io API.

Install

Install using composer:

$ composer require jabranr/postcodes-io

Documentation

All of the following methods return back the same complete response as it comes from postcodes.io API in JSON format.

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

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

use Jabranr\PostcodesIO\PostcodesIO;

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

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

use Jabranr\PostcodesIO\PostcodesIO;

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

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

use Jabranr\PostcodesIO\PostcodesIO;

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

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

use Jabranr\PostcodesIO\PostcodesIO;

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

Find nearest outcodes

use Jabranr\PostcodesIO\PostcodesIO;

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

Find an outcode by location

use Jabranr\PostcodesIO\PostcodesIO;

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

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

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

MIT License © 2016 – present | Jabran Rafique

postcodes-io's People

Contributors

jabranr avatar jamieburchell avatar

Stargazers

avatar avatar avatar avatar avatar avatar avatar avatar avatar

Watchers

avatar avatar avatar

Forkers

spamoom insitesdigital-mo pareshsojitra

postcodes-io's Issues

400 bad request when calling validate on specific text

Call validate('Willoughby Hedge') and you'll get a 400 bad request from file_get_contents(). Change it to validate('Willoughby hedge') and you'll get back the expected response object with result false.

When I used Postman directly to call the API, both worked:

https://api.postcodes.io/postcodes/Willoughby Hedge/validate:

{
    "status": 200,
    "result": false
}

https://api.postcodes.io/postcodes/Willoughby hedge/validate

{
    "status": 200,
    "result": false
}

This issue can be reproduced outside of the library:

$ php -r "echo file_get_contents('https://api.postcodes.io/postcodes/Willoughby Hedge/validate');"

PHP Warning:  file_get_contents(https://api.postcodes.io/postcodes/Willoughby Hedge/validate): Failed to open stream: HTTP request failed! HTTP/1.1 400 Bad Request
 in Command line code on line 1
PHP Stack trace:
PHP   1. {main}() Command line code:0
PHP   2. file_get_contents($filename = 'https://api.postcodes.io/postcodes/Willoughby Hedge/validate') Command line code:1

$ php -r "echo file_get_contents('https://api.postcodes.io/postcodes/Willoughby hedge/validate');"
{"status":200,"result":false}

If you urlencode the space, the problem is resolved:

$ php -r "echo file_get_contents('https://api.postcodes.io/postcodes/Willoughby%20Hedge/validate');"
{"status":200,"result":false}

Also, if your postcode contains a slash / the request fails, so this should be urlencoded too (rawurlencode).

PHP 8.1.0

PHP warning when file_get_contents gets a non 200 response

I'm wondering if this warning can/should be suppressed given the response error message is checked and an exception is thrown. One method might simply be to prefix the call with a gasp @ symbol.

I noticed cURL is used for POST but not GET; perhaps more control would be had using cURL for GET too?

Extend PHP support, update phpunit to latest

  • Deprecate older PHP support
  • Extend support to PHP 7.3+
  • Update phpunit/phpunit

This may introduce some new things for tests and in the existing API, this library exposes. However, I plan to keep any API changes from a minimum to none.

Use Guzzle or jabranr/php-curl for requests

Replace internal cURL calls using jabranr/php-curl package. This has to be done with caution as this will introduce a dependency which may not be ideal. On positive side it is great to have this as package has it's own internal unit tests.

Fix Bulk Reverse Geocoding API

Fix Bulk Reverse Geocoding API so it can pass a named associated array to Postcodes.io.

Docs Reference

Also, update the API so it can accept a named associated array in the payload.

Currently

$payload = [
  ["123", "-321"], 
  ["456", "-978"]
]

Expected
In addition to the above, API from this library should also expect the following format.

$payload = [
  ["latitude" => "123", "longitude" => "-321"], 
  ["latitude" => "456", "longitude" => "-978"]
]

Keep the changes backwards compatible

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.