PHPackages                             metapixel/postcodeapi - 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. metapixel/postcodeapi

ActiveLibrary

metapixel/postcodeapi
=====================

Universal PHP Postcode API.

1.0.0(2y ago)13PHPPHP ^8.1

Since May 20Pushed 2y ago1 watchersCompare

[ Source](https://github.com/sdrenth/PostcodeAPI)[ Packagist](https://packagist.org/packages/metapixel/postcodeapi)[ RSS](/packages/metapixel-postcodeapi/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (5)Versions (2)Used By (0)

PostcodeAPI
===========

[](#postcodeapi)

[![Tests](https://github.com/sdrenth/PostcodeAPI/actions/workflows/tests.yml/badge.svg)](https://github.com/sdrenth/PostcodeAPI/actions/workflows/tests.yml/badge.svg)

This package implements a generic approach for retrieving address details based on zipcode and housenumber to perform address validation. The goal of this package is to have a single package which supports your favorite Postcode API providers so you can easily switch between providers without having to rewrite all of your code or need to have extensive knowledge about all the providers, because this package handles that for you.

This package is platform independent and can be used in any modern PHP application.

Providers
---------

[](#providers)

The following providers are currently supported:

- [Apicheck.nl](https://apicheck.nl/)
- [Postcodeapi.nu](Postcodeapi.nu)
- [Postcode.nl](https://www.postcode.nl/)
- [Postcodeservice.com](https://postcodeservice.com/)
- [Postcodes.nu](https://postcodes.nu/)
- [Postcode.tech](https://postcode.tech/)
- [PostNL](https://www.postnl.nl/)
- [Pro6PP](https://www.pro6pp.nl/)
- [Spikkl](https://www.spikkl.nl/)

### Events

[](#events)

Pre and post search events are dispatched using the Symfony Event Dispatcher component.

The `PreSearchRequestEvent` and `PostSearchRequestEvent` allows you to add some additional custom logic, for example adding your own caching mechanism.

If you set the address in the `PreSearchRequestEvent`, the search methods will return the address object which will prevent doing an API call.

```
class PostcodeAPISubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [
            PreSearchRequestEvent::NAME => 'onPreSearchRequestEvent',
        ];
    }

    public function onPreSearchRequestEvent(PreSearchRequestEvent $event): void
    {
        $cachedAddress = new Address();
        $cachedAddress->setCountry('Nederland');
        $cachedAddress->setCountryCode('nl');
        $cachedAddress->setCity('Amsterdam');

        $event->setAddress($cachedAddress);
    }
}
```

Additional features to be developed:

- Adding an optional caching layer to cache address responses (perhaps database)?
- Adding events before or after retrieving the response.

Usage example
-------------

[](#usage-example)

See the example below on how to use this package. Please note to always provide the provider as `{locale}.{Provider class}`.

```
use Metapixel\PostcodeAPI\Provider\nl_NL\Pro6PP;

/** @var Pro6PP $provider */
$provider = ProviderFactory::create('nl_NL.Pro6PP');
$provider->setApiKey('YOUR_API_KEY');

// Optionally add an event subscriber or event listener.
$subscriber = new PostcodeAPISubscriber();
$provider->dispatcher->addSubscriber($subscriber);

$address = $provider->findByZipcodeAndHouseNumber('1068NM', '461');
```

### Search methods

[](#search-methods)

```
$provider = ProviderFactory::create('nl_NL.Pro6PP');
$provider->setApiKey('YOUR_API_KEY');

$provider->find('1068NM');
$provider->findByZipcode('1068NM');
$provider->findByZipcodeAndHousenumber('1068NM', '461');

// Using the more dynamic SearchRequest entity
$searchRequest = (new SearchRequest())
            ->setZipcode($zipcode)
            ->setHouseNumber($houseNumber);

$provider->findBySearchRequest($searchRequest);
```

If a search method is not supported, the `MethodNotSupportedException` is thrown, for example for Dutch addresses it is common that both zipcode and housenumber fields are required, so searching without housenumbers can throw a `MethodNotSupportedException` exception.

The `SearchRequest` entity is used for more dynamic Postcode API implementations which require more flexibility on which data is passed to the API.

Donate
------

[](#donate)

[![](https://raw.githubusercontent.com/andreostrovsky/donate-with-paypal/master/blue.svg)](https://paypal.me/sndrenth/)
If you enjoyed this project — or just feeling generous, consider buying me a beer. Cheers! 🍻

###  Health Score

23

—

LowBetter than 27% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity5

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 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

Unknown

Total

1

Last Release

1094d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/9939bf86d9e19894e4e36219c8ba5668215b0092c705c5d169601c8de4d509c9?d=identicon)[sdrenth](/maintainers/sdrenth)

---

Top Contributors

[![sdrenth](https://avatars.githubusercontent.com/u/7802465?v=4)](https://github.com/sdrenth "sdrenth (2 commits)")

---

Tags

postcode

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StyleECS

Type Coverage Yes

### Embed Badge

![Health badge](/badges/metapixel-postcodeapi/health.svg)

```
[![Health](https://phpackages.com/badges/metapixel-postcodeapi/health.svg)](https://phpackages.com/packages/metapixel-postcodeapi)
```

###  Alternatives

[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.6M651](/packages/sylius-sylius)[drupal/core

Drupal is an open source content management platform powering millions of websites and applications.

19462.3M1.3k](/packages/drupal-core)[drupal/core-recommended

Locked core dependencies; require this project INSTEAD OF drupal/core.

6939.5M343](/packages/drupal-core-recommended)[laravel-zero/framework

The Laravel Zero Framework.

3371.4M369](/packages/laravel-zero-framework)[civicrm/civicrm-core

Open source constituent relationship management for non-profits, NGOs and advocacy organizations.

728272.9k20](/packages/civicrm-civicrm-core)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

595.2M386](/packages/shopware-core)

PHPackages © 2026

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