freshheads/postcode-api-client

Client library for the postcodeapi.nu web service.

4.1.1 2022-04-15 15:02 UTC

Requires

• php: >=7.4
• ext-json: *
• guzzlehttp/psr7: ^2.0
• psr/http-client: ^1.0

Requires (Dev)

• php-http/mock-client: ^1.3.0
• phpunit/phpunit: ^7.5 || ^8.2

Suggests

• php-http/guzzle6-adapter: An HTTPlug adapter for the Guzzle 6 HTTP client

MIT

• Joost Farla
• Gijs Nieuwenhuis

• api
• client
• postcode

README

FHPostcodeAPIClient is a PHP client library for the PostcodeAPI.nu web service. This library is developed by Freshheads and will be maintained in sync with the web service itself.

Links:

• More information
• API documentation

Installation

FHPostcodeAPIClient can easily be installed using Composer:

composer require freshheads/postcode-api-client

Usage

Instantiate the client and replace the API key with your personal credentials:

// Use the composer autoloader to load dependencies
require_once 'vendor/autoload.php';

// initiate client
$apiKey = 'replace_with_your_own_api_key';
// In this example we made use of the Guzzle as HTTPClient.
$client = new \FH\PostcodeAPI\Client(
    new GuzzleHttp\Client([
        'headers' => [
            'X-Api-Key' => $apiKey
        ]
    ])
);

// call endpoints
$response = $client->getAddresses('5041EB', 21);
$response = $client->getAddress('0855200000061001');
$response = $client->getPostcodeDataByPostcode('5041EB');

// Note that this call is only available with a premium account
$response = $client->getPostcodes('51.566405', '5.077171');

Within a Symfony project

We recommend to use Guzzle, to be able to use Guzzle in combination with the PostcodeApiClient. Following definition is used with an implementation of Guzzle 7.

_defaults:
        autowire: true
        autoconfigure: true

    project.http.client.postal_code:
        class: GuzzleHttp\Client
        bind:
            $config: { headers: { X-Api-Key: '%postcode_api_nu.key%' } }

    FH\PostcodeAPI\Client:
        $httpClient: '@project.http.client.postal_code'

You should now be able use the FH\PostcodeAPI\Client service to make requests to the PostcodeAPI.

Guzzle 6

To make use of Guzzle 6, you should also make use of the Guzzle6Adapter. By running the following command you automatically install Guzzle as well.

composer require php-http/guzzle6-adapter

And add the following service definitions (usable in Symfony ^3.4):

services:
    _defaults:
        autowire: true
        autoconfigure: true

    project.http.guzzle.client:
        class: GuzzleHttp\Client
        arguments:
            - { headers: { X-Api-Key: 'replace_with_your_own_api_key_or_variable' } }
    
    project.http.adapter.guzzle.client:
        class: Http\Adapter\Guzzle6\Client
        arguments:
            $client: '@project.http.guzzle.client'
    
    FH\PostcodeAPI\Client:
        $httpClient: '@project.http.adapter.guzzle.client'