README

Nederland Postcode Laravel makes it easy to integrate Dutch address validations into your Laravel application using the Nederland Postcode API.

This is a Laravel wrapper for the Nederland Postcode PHP package.

Requirements
Installation
Usage
- Address Endpoint
  - Single Address
  - Multiple Addresses
- Quota Endpoint
Error Handling

Requirements

Laravel 12.x
PHP 8.2+

Installation

Install the package via Composer:

composer require label84/laravel-nederland-postcode

Publish the configuration file:

php artisan vendor:publish --provider="Label84\NederlandPostcode\Laravel\NederlandPostcodeServiceProvider" --tag="config"

Add your API key to your .env file:

NEDERLAND_POSTCODE_API_KEY="your_api_key_here"

Usage

Address Endpoint

The address endpoint allows you to fetch address information from the Nederland Postcode API.

You can search addresses using either the find method for a single address or the list method for multiple addresses. The find method will throw an exception if no address is found or if multiple addresses are found for the given postcode and house number (ie. when the house number has multiple additions like A, B, C, etc.).

The following optional attributes can be requested to be included in the response:

coordinates: Includes latitude and longitude of the address.

Single Address

To fetch a single address for a given postcode and house number, you can use the find method.

The postcode and number parameters are required. The addition parameter is optional.

use Label84\NederlandPostcode\Laravel\Facades\NederlandPostcode;

$address = NederlandPostcode::find(
        postcode: '1118BN',
        number: 800,
        addition: null,
        attributes: [
            'coordinates',
        ]
    );

This will return an Address object like this:

Address {
    postcode: "1118BN",
    number: 800,
    addition: null,
    street: "Schiphol Boulevard",
    city: "Schiphol",
    municipality: "Haarlemmermeer",
    province: "Noord-Holland",
    coordinates: Coordinates {
        latitude: 52.30528553688755,
        longitude: 4.750645160863609
    }
}

When no address is found for the given postcode and number, an AddressNotFoundException is thrown. If multiple addresses are found, a MultipleAddressesFoundException is thrown.

Multiple Addresses

To fetch multiple addresses for a given postcode and house number, you can use the list method.

The postcode and number parameters are required. The addition parameter is optional.

use Label84\NederlandPostcode\Laravel\Facades\NederlandPostcode;

$addresses = NederlandPostcode::list(
        postcode: '1015CN',
        number: 10,
        addition: null,
        attributes: [
            'coordinates',
        ]
    );

This will return an AddressCollection object like this:

AddressCollection {
    items: [
        Address {
            postcode: "1015CN",
            number: 10,
            addition: 'A',
            street: "Keizersgracht",
            city: "Amsterdam",
            municipality: "Amsterdam",
            province: "Noord-Holland",
            coordinates: Coordinates {
                latitude: 52.379401496779124,
                longitude: 4.889216673725493
            }
        },
        Address {
            postcode: "1015CN",
            number: 10,
            addition: 'B',
            street: "Keizersgracht",
            city: "Amsterdam",
            municipality: "Amsterdam",
            province: "Noord-Holland",
            coordinates: Coordinates {
                latitude: 52.379401496779124,
                longitude: 4.889216673725493
            }
        },
        Address {
            postcode: "1015CN",
            number: 10,
            addition: 'C',
            street: "Keizersgracht",
            city: "Amsterdam",
            municipality: "Amsterdam",
            province: "Noord-Holland",
            coordinates: Coordinates {
                latitude: 52.379401496779124,
                longitude: 4.889216673725493
            }
        },
        Address {
            postcode: "1015CN",
            number: 10,
            addition: 'D',
            street: "Keizersgracht",
            city: "Amsterdam",
            municipality: "Amsterdam",
            province: "Noord-Holland",
            coordinates: Coordinates {
                latitude: 52.379401496779124,
                longitude: 4.889216673725493
            }
        },
    ]
}

Quota Endpoint

The quota endpoint allows you to check your current API usage and limits. This endpoint does not increase your usage quota.

Note

Values may lag behind the actual usage. They're cached for up to five minutes, so the used and limit numbers might not be fully up-to-date.

use Label84\NederlandPostcode\Laravel\Facades\NederlandPostcode;

$quota = NederlandPostcode::usage();

This will return an Quota object like this:

Quota {
    used: 1500,
    limit: 10000,
}

Error Handling

The package throws a NederlandPostcodeException for any errors encountered during the API request. You can catch this exception to handle errors gracefully:

use Label84\NederlandPostcode\Exceptions\NederlandPostcodeException;

try {
    $addresses = NederlandPostcode::find(
        postcode: 'INVALID',
        number: 123,
        addition: null,
    );
} catch (NederlandPostcodeException $exception) {
    // handle error
}

When calling the find method, if no address is found, an AddressNotFoundException is thrown. If multiple addresses are found, a MultipleAddressesFoundException is thrown.

When a network or HTTP error occurs during the API request, a NederlandPostcodeRequestException is thrown, which wraps the original RequestException.

Contributing

./vendor/bin/phpstan analyse

./vendor/bin/pint

./vendor/bin/phpunit

License

MIT

label84 / laravel-nederland-postcode

Maintainers

Details