README

MTS-K DATEX II v2 petrol-station helpers for Pulp pipelines. Two layers: Mobilithek source defaults, then presentation-neutral XML → GeoJSON.

This package is not AFIR charging (mapsight/pulp-datex-energy).

Features

Mobilithek src helper: Configures Pulp::srcHttp with the default subscription URL, Accept-Encoding: gzip, and P12 client-cert curl options. Certificate path, password, and subscription ID stay caller-supplied.
Grunddaten → GeoJSON: One point feature per PetrolStation from a PetrolStationPublication.
Preisdaten: FuelPrice records for Super E5, Super E10, and Diesel, joined to stations on the station GUID.
Bounding box filtering: Limits stations to [minLon, minLat, maxLon, maxLat].
Presentation-neutral output: Source and data properties only. Applications add icons, HTML descriptions, and localized labels afterwards.

Access

Consumer pull of the aggregated MTS-K collector feeds requires Verbraucher-Informationsdienst admission under § 6 MTSKraftV (nationwide, permanent, unrestricted) or a VID third-party regional feed (the VID stays liable). This package only parses publications you already have a right to fetch. It does not apply for VID status and does not check legal eligibility at runtime.

Installation

composer require mapsight/pulp-datex-fuel

This package depends on mapsight/pulp and mapsight/pulp-mobilithek.

Fetch a subscription

use OpenMapsight\Pulp;
use OpenMapsight\PulpCache;
use OpenMapsight\PulpDatexFuel;
use OpenMapsight\PulpJSON;

$source = Pulp::start()
    ->pipe(PulpDatexFuel::srcMobilithek(
        $subscriptionId,
        $certPath,
        $certPassword,
        $ifModifiedSince,
    ));

$files = Pulp::start()
    ->pipe(PulpCache::remember($source, __DIR__ . '/cache', [
        'key' => 'datex-fuel-stations',
        'ttl' => 86400,
        'fallbackToStale' => true,
    ]))
    ->pipe(PulpDatexFuel::stationsGeoJson(
        bbox: [6.05, 50.76, 6.08, 50.82],
        sourceUrl: 'https://example.com/open-data-docs',
        sourceName: 'DATEX Fuel',
        documentationUrl: 'https://example.com/open-data-docs',
        publicSourceUrl: 'https://example.com/open-data-docs',
    ))
    ->run();

Pulp::srcHttp still loads the full response body as a string. A nationwide dump may need a disk sink in core pulp later. That belongs in core pulp, not this package.

Stations GeoJSON

use OpenMapsight\Pulp;
use OpenMapsight\PulpDatexFuel;
use OpenMapsight\PulpJSON;

Pulp::start()
    ->pipe(Pulp::src('stations.xml', __DIR__ . '/input'))
    ->pipe(PulpDatexFuel::stationsGeoJson(
        [6.05, 50.76, 6.08, 50.82],
        'https://example.com/open-data-docs',
    ))
    ->pipe(PulpJSON::encodeJSON(JSON_PRETTY_PRINT))
    ->pipe(Pulp::dest(__DIR__ . '/result'))
    ->run();

The handler accepts a DATEX II v2 XML string, a Mobilithek SOAP container, or an already-decoded array. Stations without coordinates are dropped.

Price merge

$prices = PulpDatexFuel::extractPrices($publication);
$cache = PulpDatexFuel::applyPricePacketToCache($cache, $prices, $packetType, $lastModified);
$merged = PulpDatexFuel::mergePricesIntoFeatureCollection($featureCollection, $cache['prices']);

Or in a pipeline:

Pulp::start()
    ->pipe(Pulp::src('prices.xml', __DIR__ . '/input'))
    ->pipe(PulpDatexFuel::priceRecords())
    ->run();

To keep an on-disk accumulator across runs (and to ignore 304/204 packets):

Pulp::start()
    ->pipe(Pulp::src('prices.xml', __DIR__ . '/input'))
    ->pipe(PulpDatexFuel::accumulatePrices(__DIR__ . '/cache/tanken-prices.json'))
    ->run();

A SNAPSHOT packet replaces the station-price cache. A DELTA packet upserts by station GUID. Published MTS-K examples are snapshots; the DELTA path is the hook if a collector later sends increments.

Station properties

Station features include:

stationId (GUID)
name
brand, operator (empty string when the publication omits them)
addressLine, postcode, city, countryCode
openingHours (DATEX-derived list of {days, periods} blocks; days use DATEX DayEnum values such as monday and publicHoliday)
stationUpdatedAt
source, sourceUrl

After a price merge, matched features also include:

e5, e10, diesel (float with up to three decimals, or null when that product is absent)
pricesUpdatedAt (dateOfPrice / Änderungszeitpunkt)

Notes

Certificate path, password, and subscription ID stay caller-supplied.
Presentation (icons, localized copy, price comparison) belongs in the consuming application.
srcMobilithek() only configures Pulp::srcHttp. Cache with PulpCache::remember. The same helper is also available as PulpMobilithek::srcMobilithek().

mapsight / pulp-datex-fuel

Maintainers

Package info

Statistics

Security