README

A Laravel client for the BayernPortal REST API v3, the official directory of Bavarian public administration. It covers agencies, authorities, buildings, contact persons, services, service descriptions, forms, online procedures and life situations.

English API. Every class, method, property and parameter has an English name. The German REST names only appear on the wire. See the glossary.
Typed, immutable DTOs. Responses map to readonly objects with value objects for addresses, phone numbers, opening hours and images. The raw payload is always available as raw.
Pagination built in. Use Page objects with next(), or a lazy all() that fetches pages only while you iterate.
Municipality scope. BayernPortal::forMunicipality('09162000') localises every request that supports it.
Optional response caching, retries on server errors, and typed exceptions that keep the API's original (German) error message.
Testing helpers. BayernPortal::fake() answers every endpoint with realistic fixtures.

use Rathauslotse\BayernPortal\Facades\BayernPortal;

$munich = BayernPortal::forMunicipality('09162000');

foreach ($munich->services()->list() as $service) {
    echo $service->name, PHP_EOL;              // "Personalausweis beantragen"
}

$description = $munich->serviceDescriptions()->find(1010);

$description->fees;                            // "37,00 Euro (ab 24 Jahren)"
$description->responsibilities[0]->name;       // "Kreisverwaltungsreferat München"
$description->forms[0]->url;                   // "https://…/antrag.pdf"

Requirements

PHP 8.3 or newer
Laravel 12 or 13
BayernPortal web service credentials (how to get them)

Installation

composer require rathauslotse/bayernportal-api

The service provider and the BayernPortal facade are registered automatically. Add your credentials to .env:

BAYERNPORTAL_USERNAME=your-user
BAYERNPORTAL_PASSWORD=your-password

Optionally publish the config file:

php artisan vendor:publish --tag=bayernportal-config

Quick start

use Rathauslotse\BayernPortal\Enums\Weekday;
use Rathauslotse\BayernPortal\Facades\BayernPortal;

// Agencies (Dienststellen), paginated
$page = BayernPortal::agencies()->list(size: 50);
$page->total;                     // X-Total-Count
$page->next();                    // next Page or null

// …or iterate everything lazily
BayernPortal::agencies()->all()->each(fn ($agency) => /* … */);

// One agency and what it offers
$agency = BayernPortal::agencies()->find('0916200');
BayernPortal::agencies()->formsByService('0916200', '09162000');

// Authorities, buildings, contacts
$building = BayernPortal::authorities()->building(4711, 801);
$building->streetAddress->format();          // "Ruppertstraße 19, 80337 München"
$building->phone?->format();                 // "+49 89 233-96000"
$building->openingHours?->forDay(Weekday::Tuesday);

// Life situations as a tree
BayernPortal::lifeSituations()->tree();

Without the facade, inject Rathauslotse\BayernPortal\BayernPortal.

Documentation

Topic
Getting started	Installation · Configuration · Authentication
Endpoints	Agencies · Authorities & buildings · Contacts · Services · Service descriptions · Life situations
Concepts	Municipality scope · Pagination · Caching · Error handling
Reference	Data model · Glossary (German → English) · API quirks
Development	Testing · Contributing · Changelog

License

MIT. See LICENSE.

rathauslotse / bayernportal-api

Package info

Security

Statistics