PHPackages                             label84/php-nederland-postcode - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Validation & Sanitization](/categories/validation)
4. /
5. label84/php-nederland-postcode

ActiveLibrary[Validation & Sanitization](/categories/validation)

label84/php-nederland-postcode
==============================

Integrate Dutch address validations into your PHP application using the Nederland Postcode API.

1.3.0(2mo ago)13151MITPHPCI passing

Since Dec 8Pushed 2mo agoCompare

[ Source](https://github.com/Label84/php-nederland-postcode)[ Packagist](https://packagist.org/packages/label84/php-nederland-postcode)[ RSS](/packages/label84-php-nederland-postcode/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (4)Dependencies (6)Versions (6)Used By (1)

Nederland Postcode PHP
======================

[](#nederland-postcode-php)

[![Nederland Postcode API](./docs/nederlandpostcodeapi.png)](./docs/nederlandpostcodeapi.png)

Nederland Postcode PHP makes it easy to integrate Dutch address validations into your PHP application using the [Nederland Postcode API](https://nederlandpostcode.nl).

Register for free to obtain a **test API key** at [nederlandpostcode.nl](https://nederlandpostcode.nl) to get started.

- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
    - [Address Endpoint](#address-endpoint)
        - [Single Address](#single-address)
        - [Multiple Addresses](#multiple-addresses)
    - [Energy Label Endpoint](#energy-label-endpoint)
    - [Quota Endpoint](#quota-endpoint)
- [Error Handling](#error-handling)

Requirements
------------

[](#requirements)

- PHP 8.2+

Installation
------------

[](#installation)

Install the package via Composer:

```
composer require label84/php-nederland-postcode
```

Usage
-----

[](#usage)

```
require_once __DIR__ . '/vendor/autoload.php';

use Label84\NederlandPostcode\NederlandPostcodeClient;

$client = new NederlandPostcodeClient(
    key: 'npa_live_XXX',
);

try {
    $address = $client->find(
        postcode: '1118BN',
        number: 800,
        attributes: ['coordinates'],
    );
} catch (NederlandPostcodeException $exception) {
    // handle exception
}

echo $address->street; // Schiphol Boulevard
echo $address->coordinates->latitude; // 52.30703569036619
```

### Address Endpoint

[](#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.
- `district`: Includes the official and name of the district that the address belongs to.
- `function`: Includes the function of the address (e.g. residential, commercial, healthcare, etc.).
- `location_status`: Includes the location status of the address (e.g. active, in development, etc.).
- `property_status`: Includes the property status of the address (e.g. in use, under construction, etc.).
- `surface_area`: Includes the surface area of the property in square meters.
- `construction_year`: Includes the construction year of the property.

#### Single 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\NederlandPostcodeClient;

$client = new NederlandPostcodeClient(
    key: 'npa_live_XXX'
);

$address = $client->find(
    postcode: '1118BN',
    number: 800,
    addition: null,
    attributes: [
        AddressAttributesEnum::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
    },
    district: District {
        official: "Schiphol",
        name: "Schiphol"
    },
    function: "kantoorfunctie",
    location_status: "verblijfsobject in gebruik",
    property_status: "pand in gebruik",
    surface_area: 10398.0,
    construction_year: 2019
}
```

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

[](#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\NederlandPostcodeClient;

$client = new NederlandPostcodeClient(
    key: 'npa_live_XXX'
);

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

This will return an `AddressCollection` like this:

```
AddressCollection {
    items: [
        Address {
            postcode: "1015CN",
            number: 10,
            addition: "A",
            street: "Keizersgracht",
            city: "Amsterdam",
            municipality: "Amsterdam",
            province: "Noord-Holland",
            country: "Nederland",
            coordinates: Coordinates { ... }
            ...
        },
        Address {
            postcode: "1015CN",
            number: 10,
            addition: "B",
            street: "Keizersgracht",
            ...
        }
    ]
}
```

### Energy Label Endpoint

[](#energy-label-endpoint)

The energy label endpoint allows you to fetch energy label information for a given postcode and house number (with optional addition).

```
use Label84\NederlandPostcode\NederlandPostcodeClient;

$client = new NederlandPostcodeClient(
    key: 'npa_live_XXX'
);

$energyLabels = $client->energyLabels()->get(
    postcode: '1118BN',
    number: 800,
    addition: null,
);
```

This will return an `EnergyLabelCollection` like this:

```
EnergyLabelCollection {
    items: [
        EnergyLabel {
            postcode: "1118BN",
            number: 800,
            addition: null,
            street: "Schiphol Boulevard",
            city: "Schiphol",
            inspectionDate: DateTime("2022-08-02"),
            validUntilDate: DateTime("2032-08-02"),
            constructionType: "utiliteitsbouw",
            buildingType: null,
            energyLabel: "A+++",
            maxEnergyDemand: 98.4,
            maxFossilEnergyDemand: 55.48,
            minRenewableShare: 55.3
        }
    ]
}
```

### Quota Endpoint

[](#quota-endpoint)

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

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\NederlandPostcodeClient;

$client = new NederlandPostcodeClient(
    key: 'npa_live_XXX'
);

$quota = $client->usage();
```

This will return an `Quota` object like this:

```
Quota {
    used: 1500,
    limit: 10000,
}
```

Error Handling
--------------

[](#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;

$client = new NederlandPostcodeClient(
    key: 'npa_live_XXX'
);

try {
    $addresses = $client->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
------------

[](#contributing)

```
./vendor/bin/phpstan analyse
```

```
./vendor/bin/phpunit
```

License
-------

[](#license)

[MIT](https://opensource.org/licenses/MIT)

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance86

Actively maintained with recent releases

Popularity18

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity39

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~30 days

Total

4

Last Release

69d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/78c37d1496f19445af6a812d2275c34bbd08dead68aebae70229d7ff0670ed85?d=identicon)[tjardo](/maintainers/tjardo)

---

Top Contributors

[![tjardoo](https://avatars.githubusercontent.com/u/31533540?v=4)](https://github.com/tjardoo "tjardoo (11 commits)")

---

Tags

phpphp-package

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/label84-php-nederland-postcode/health.svg)

```
[![Health](https://phpackages.com/badges/label84-php-nederland-postcode/health.svg)](https://phpackages.com/packages/label84-php-nederland-postcode)
```

###  Alternatives

[aporat/store-receipt-validator

PHP receipt validator for Apple App Store and Amazon Appstore

6503.9M9](/packages/aporat-store-receipt-validator)[robertogallea/laravel-codicefiscale

Codice fiscale validation for php/laravel

58151.6k1](/packages/robertogallea-laravel-codicefiscale)[deligoez/tckimlikno

Turkish Identification Number Verification & Validation Package for Laravel

2917.4k](/packages/deligoez-tckimlikno)[speelpenning/laravel-postcode-nl

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

1221.1k](/packages/speelpenning-laravel-postcode-nl)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)