README

A client using the Postcode.nl REST API for Dutch address verification.

All the work for this package has been done by Gerben Speelpenning, I merely updated to composer.json to make it work with Laravel 10 and submitted it to Packagist for easy installation, but if there is anything that does not work either because of the Laravel update or updates to the PostcodeNL API please let me know so I can fix them!

Installation

Pull the package in through Composer:

composer require pimoudeveldhuis/laravel-postcode-nl

Next, register an account with Postcode.nl to obtain a key and secret. See https://api.postcode.nl/#register for further information. Once you have a key and secret, store them in your .env file.

Add the following service provider to your application config:

Speelpenning\PostcodeNl\PostcodeNlServiceProvider::class,

Walk through the configuration section to make things work.

Usage

There are two ways to use the address lookup: by injecting the address lookup service in your code or using the AddressController that is shipped with the package.

Dependency injection

Example:

<?php

use Exception;
use Speelpenning\PostcodeNl\Services\AddressLookup;

class AddressDumper {

    /**
     * @var AddressLookup
     */
    protected $lookup;
    
    /**
     * Create an address dumper instance.
     *
     * @param AddressLookup $lookup
     */
    public function __construct(AddressLookup $lookup)
    {
        $this->lookup = $lookup;
    }
    
    /**
     * Dumps the address details on screen.
     *
     * @param string $postcode
     * @param int $houseNumber
     * @param null|string $houseNumberAddition
     */
    public function dump($postcode, $houseNumber, $houseNumberAddition = null)
    {
        try {
            $address = $this->lookup->lookup($postcode, $houseNumber, $houseNumberAddition);
            dd($address);
        }
        catch (Exception $e) {
            exit('Ow, that went wrong...');
        }
    }

}

Using the JSON API

In order to use the API, enabled it in the configuration. When enabled, the following route is available:

route('postcode-nl::address', [$postcode, $houseNumber, $houseNumberAddition = null]);

or use the following URL (e.g. for AJAX calls):

/postcode-nl/address/{postcode}/{houseNumber}/{houseNumberAddition?}

Configuration

Credentials (required)

The key and secret are used for authentication. Without them, you cannot use the service.

POSTCODENL_KEY=<your-api-key>
POSTCODENL_SECRET=<your-secret>

Enable routes (optional)

This package comes with a ready to use JSON API, which is disabled by default. You can enable it like so:

POSTCODENL_ENABLE_ROUTES=true

Timeout (in seconds, optional)

By default, the client waits 10 seconds for a response. You may set a different timeout.

POSTCODENL_TIMEOUT=<timeout-in-seconds>