PHPackages                             api-check/php-client - 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. [API Development](/categories/api)
4. /
5. api-check/php-client

ActiveLibrary[API Development](/categories/api)

api-check/php-client
====================

A wrapper around ApiCheck API to validate addresses.

v2.0.0(3mo ago)08042MITPHPPHP ^7.4|^8.0|^8.1|^8.2|^8.3|^8.5CI passing

Since Oct 9Pushed 3mo ago2 watchersCompare

[ Source](https://github.com/api-check/php-client)[ Packagist](https://packagist.org/packages/api-check/php-client)[ Docs](https://apicheck.nl/)[ RSS](/packages/api-check-php-client/feed)WikiDiscussions main Synced today

READMEChangelog (2)Dependencies (5)Versions (3)Used By (2)

ApiCheck PHP Client
===================

[](#apicheck-php-client)

A PHP client for the ApiCheck API. Validate addresses, search locations, and verify contact data with ease.

**Version:** 2.0.0

Features
--------

[](#features)

- **Lookup API** - Validate postal addresses (NL, LU)
- **Search API** - Search cities, streets, postal codes, and addresses across 18 European countries
- **Verify API** - Verify email addresses and phone numbers

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

[](#requirements)

- PHP 8.1 or higher
- Register an account at [ApiCheck Dashboard](https://app.apicheck.nl/authentication/register)
- Create an API key

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

[](#installation)

Install via Composer:

```
composer require api-check/php-client:^2.0
```

Or add to your `composer.json`:

```
{
  "require": {
    "api-check/php-client": "^2.0"
  }
}
```

Quick Start
-----------

[](#quick-start)

```
use ApiCheck\Api\ApiClient;

require "./vendor/autoload.php";

$client = new ApiClient();
$client->setApiKey("YOUR_API_KEY");

// Optionally set a referer if your API key has allowed hosts configured
$client->setReferer("https://your-domain.com");
```

Lookup API
----------

[](#lookup-api)

Look up addresses by postal code and house number. Currently supported for NL and LU.

[Lookup API documentation](https://apicheck.nl/documentation/lookup-api/)

### Basic Lookup

[](#basic-lookup)

```
$address = $client->lookup('nl', [
    'postalcode' => '2513AA',
    'number' => 1
]);

print("{$address->street} {$address->number}\n");
print("{$address->postalcode} {$address->city}\n");
print("{$address->Country->name}");
```

### Advanced Options

[](#advanced-options)

```
$address = $client->lookup('nl', [
    'postalcode' => '2513AA',
    'number' => 1,
    'fields' => ['street', 'city', 'latitude', 'longitude'],  // Only return specific fields
    'aliasses' => true,    // Include subaddress relationships
    'shortening' => true   // Include streetShort field
]);
```

### Get Number Additions

[](#get-number-additions)

Retrieve available number additions (like "A", "B", "1e") for a postal code:

```
$additions = $client->getNumberAdditions('nl', '2513AA', '1');
// Returns: ["1", "1A", "1B", ...]
```

Search API
----------

[](#search-api)

Search for cities, streets, postal codes, and addresses across 18 European countries.

[Search API documentation](https://apicheck.nl/documentation/normalised-search-api/)

### Basic Search

[](#basic-search)

```
// Search cities
$results = $client->search('be', 'city', ['name' => 'Namur']);

// Search streets
$results = $client->search('nl', 'street', ['name' => 'Hoofd']);

// Search postal codes
$results = $client->search('fr', 'postalcode', ['name' => '75001']);
```

### Global Search

[](#global-search)

Search across all scopes at once:

```
$results = $client->globalSearch('nl', 'Hoofdf', [
    'limit' => 10
]);
```

### Belgium-Specific Searches

[](#belgium-specific-searches)

Search localities (deelgemeenten) and municipalities (gemeenten):

```
// Search localities
$localities = $client->searchLocality('be', 'Gontrode');

// Search municipalities
$municipalities = $client->searchMunicipality('be', 'Gent');
```

### Address Resolution

[](#address-resolution)

Resolve a full address using IDs from previous searches:

```
$address = $client->searchAddress('be', [
    'street_id' => 12345,
    'number' => '10',
    'postalcode_id' => 67890
]);
```

### Get Supported Countries

[](#get-supported-countries)

Retrieve the live list of supported countries:

```
$countries = $client->getSupportedSearchCountries();
```

Verify API
----------

[](#verify-api)

Verify email addresses and phone numbers.

### Email Verification

[](#email-verification)

```
$result = $client->verifyEmail('user@example.com');

// Returns:
// - disposable_email: bool
// - greylisted: bool
// - status: "valid" | "invalid" | "unknown"

if ($result->status === 'valid' && !$result->disposable_email) {
    print("Email is valid and not disposable");
}
```

### Phone Number Verification

[](#phone-number-verification)

```
$result = $client->verifyPhone('+31612345678');

// Returns:
// - valid: bool
// - country_code: string (e.g., "NL")
// - international_formatted: string
// - number_type: string (e.g., "mobile")
```

Exception Handling
------------------

[](#exception-handling)

The client uses specific exceptions for different error scenarios:

```
use ApiCheck\Api\ApiClient;
use ApiCheck\Api\Exceptions\NotFoundException;
use ApiCheck\Api\Exceptions\ValidationException;
use ApiCheck\Api\Exceptions\UnsupportedCountryException;
use ApiCheck\Api\Exceptions\UnauthorizedException;
use ApiCheck\Api\Exceptions\ApiKeyInvalidException;
use ApiCheck\Api\Exceptions\NoExactMatchException;

try {
    $address = $client->lookup('nl', ['postalcode' => '2513AA', 'number' => 1]);
} catch (NotFoundException $e) {
    // No results found
} catch (ValidationException $e) {
    // Invalid or missing fields
} catch (UnsupportedCountryException $e) {
    // Country not supported for this operation
} catch (UnauthorizedException $e) {
    // Invalid or missing API key
} catch (NoExactMatchException $e) {
    // No exact match found (Search API)
} catch (ApiException $e) {
    // General API error
}
```

### Available Exceptions

[](#available-exceptions)

- `ApiException` - Base exception for all API errors
- `AccessDeniedException` - Access denied
- `ApiKeyExhaustedException` - API key quota exceeded
- `ApiKeyHeaderException` - API key header missing
- `ApiKeyInvalidException` - Invalid API key
- `BadRequestException` - Bad request (400)
- `HostNotAllowedException` - Host not allowed for this API key
- `InternalServerErrorException` - Server error (500)
- `NoExactMatchException` - No exact match found
- `NotFoundException` - Resource not found (404)
- `PageNotFoundException` - Page not found
- `UnauthorizedException` - Unauthorized (401)
- `UnprocessableEntityException` - Unprocessable entity (422)
- `UnsupportedCountryException` - Country not supported
- `ValidationException` - Validation failed

Examples
--------

[](#examples)

More examples can be found in the [examples/](examples/) directory:

- [Lookup examples](examples/lookup/) - Basic lookup, number additions, options
- [Search examples](examples/search/) - Basic search, global search, Belgium-specific, address resolution
- [Verify examples](examples/verify/) - Email and phone verification

Contributing
------------

[](#contributing)

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

```
composer test
```

License
-------

[](#license)

[MIT](https://choosealicense.com/licenses/mit/)

Support
-------

[](#support)

Contact: [www.apicheck.nl](https://www.apicheck.nl) —

###  Health Score

48

—

FairBetter than 93% of packages

Maintenance82

Actively maintained with recent releases

Popularity19

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity66

Established project with proven stability

 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 ~1268 days

Total

2

Last Release

95d ago

Major Versions

1.0 → v2.0.02026-03-31

PHP version history (2 changes)1.0PHP ^7.1|^8.0

v2.0.0PHP ^7.4|^8.0|^8.1|^8.2|^8.3|^8.5

### Community

Maintainers

![](https://www.gravatar.com/avatar/2fbba6e9dc0a41b3dc76f177d888dd47ab13774b796c6327e2274f6301cea6e8?d=identicon)[ApiCheck](/maintainers/ApiCheck)

---

Top Contributors

[![WouterDoornbos](https://avatars.githubusercontent.com/u/9071887?v=4)](https://github.com/WouterDoornbos "WouterDoornbos (13 commits)")

---

Tags

laravelpostal-codeaddress validationapicheckAddress Verificationaddress-api

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/api-check-php-client/health.svg)

```
[![Health](https://phpackages.com/badges/api-check-php-client/health.svg)](https://phpackages.com/packages/api-check-php-client)
```

###  Alternatives

[statamic/cms

The Statamic CMS Core Package

4.8k3.6M986](/packages/statamic-cms)[tencentcloud/tencentcloud-sdk-php

TencentCloudApi php sdk

3741.3M45](/packages/tencentcloud-tencentcloud-sdk-php)[eslazarev/wildberries-sdk

Wildberries OpenAPI clients (generated).

273.0k](/packages/eslazarev-wildberries-sdk)[moe-mizrak/laravel-openrouter

Laravel package for OpenRouter (A unified interface for LLMs)

154177.9k2](/packages/moe-mizrak-laravel-openrouter)[flat3/lodata

OData v4.01 Producer for Laravel

99351.7k](/packages/flat3-lodata)[simplestats-io/laravel-client

Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof.

5021.9k](/packages/simplestats-io-laravel-client)

PHPackages © 2026

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