b35/vivoo-poi-client

PHP client for the Vlaanderen POI OGC API Features

1.0.0 2026-05-14 08:11 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.0

Requires (Dev)

• phpunit/phpunit: ^10.0

MIT

• Bram Esposito

• geojson
• poi
• cql
• ogc
• vlaanderen
• api-features

README

PHP client for the Digitaal Vlaanderen POI OGC API Features service, with a focus on the Vlaamse Inventaris van Ongeschikte en Onbewoonbare Woningen (VIVOO) — the Flemish registry of dwellings declared unsuitable or uninhabitable by municipal mayors under Book 3 of the 2021 Flemish Housing Code.

The dataset covers single-family homes, apartments, and rooms in the Flemish Region. It is maintained by Wonen in Vlaanderen and refreshed daily. When using this data, attribution is required: "Bron: Wonen-Vlaanderen".

Requirements

• PHP 8.1+
• Composer

Installation

composer require b35/vivoo-poi-client

Usage

Basic usage

use B35\Vivoo\PoiClient;

$client = new PoiClient();

// List all available collections
$collections = $client->getCollections();

// Fetch features from a collection (with optional limit and bounding box)
$features = $client->getFeatures('POI', [
    'limit' => 10,
    'bbox'  => [2.5, 50.6, 5.9, 51.6],
]);

// Fetch a single feature by ID
$feature = $client->getFeature('POI', '12345');

Filtering with CqlFilter

CqlFilter builds CQL2-text filter strings. Pass the result as the filter parameter alongside 'filter-lang' => 'cql2-text'.

use B35\Vivoo\CqlFilter;
use B35\Vivoo\PoiClient;

$client = new PoiClient();

// Filter by address
$filter = (new CqlFilter())->address(
    straat:     'Bergensesteenweg',
    huisnummer: '709',
    gemeente:   'Sint-Pieters-Leeuw',
)->build();

$features = $client->getFeatures('POI', [
    'filter'      => $filter,
    'filter-lang' => 'cql2-text',
]);

CqlFilter methods

Method	CQL2 output
->equals('FIELD', 'value')	FIELD='value'
->like('FIELD', 'val%')	FIELD LIKE 'val%'
->address(straat, huisnummer, postcode, gemeente)	Convenience wrapper for the standard address fields

All parameters to address() are optional. Wildcards % (any string) and _ (single character) are supported in like() and in the straat parameter of address(). Matches are case-sensitive.

Multiple conditions are joined with AND:

$filter = (new CqlFilter())
    ->equals('PRODUCT', 'VlaamseInventarisOngeschikteOnbewoonbareWoningen')
    ->address(gemeente: 'Antwerpen')
    ->build();
// PRODUCT='VlaamseInventarisOngeschikteOnbewoonbareWoningen' AND GEMEENTE='Antwerpen'

All client methods

Method	Endpoint
getLandingPage()	GET /
getConformanceDeclaration()	GET /conformance
getCQLFunctions()	GET /functions
getCollections()	GET /collections
describeCollection($id)	GET /collections/{id}
getQueryables($id)	GET /collections/{id}/queryables
getFeatures($id, $params)	GET /collections/{id}/items
getFeature($id, $featureId)	GET /collections/{id}/items/{featureId}
searchFeatures($id, $body)	POST /collections/{id}/search

getFeatures() and searchFeatures() accept: limit, bbox, datetime, filter, filter-lang, filter-crs, sortby, crs, bbox-crs.

Error handling

All API and network errors throw B35\Vivoo\Exception\ApiException:

use B35\Vivoo\Exception\ApiException;

try {
    $features = $client->getFeatures('unknown-collection');
} catch (ApiException $e) {
    echo $e->getStatusCode();    // HTTP status code
    echo $e->getResponseBody();  // Raw response body
}

License

MIT