bundesAPI/deutschland: Python access to German public data

What deutschland consolidates, and for whom

deutschland solves the repeated integration work involved in calling German public data services from Python. The repository describes itself as a package for accessing important German datasets, but it is better understood as a collection of service-specific clients than as one unified national data platform. Python developers can import a module such as deutschland.geo, instantiate its client, and call a small public method instead of implementing every upstream response format themselves.

The included subjects span several domains. Geographic queries can return streets, house numbers, building geometry, and related map features. The Bundesanzeiger client searches company financial reports. The Lebensmittelwarnung client retrieves food product warnings by content type and region. The VERENA client covers substitute teaching positions in North Rhine-Westphalia. Auto-generated clients cover sources including the Bundesrat, Bundestag, DWD, Interpol, job search, and charging stations. The README also says that Handelsregister support moved to the separate bundesAPI/handelsregister repository.

This package is aimed at developers who already know which German public source they need. It does not present a catalog model, cross-source entity resolver, or common schema. For example, the geographic response is organized by German feature categories, while the Bundesanzeiger response is a dictionary of report names and the VERENA response is a list of position records. That variation makes the package convenient when a project uses one or a few modules, but less predictable when every source must support the same application-wide interface.

Inside the Python wrappers and their data flow

The repository layout places the distributable package under src/deutschland, with Poetry configuration in pyproject.toml. The public examples instantiate small client objects, pass query parameters, and receive decoded Python structures. The geographic client uses two coordinate pairs. The Lebensmittelwarnung client receives a content type and region. The Bundesanzeiger client receives a search term. VERENA requires no query in the documented basic call.

The geographic endpoint is the clearest structured-data case. Its README example sends top-right and bottom-left coordinates to Geo.fetch and receives a dictionary whose keys include Adresse, Barrierenlinie, Bauwerksflaeche, Gebaeudepunkte-related categories, Verkehrsflaeche, and Hintergrund. Individual entries use GeoJSON-style fields such as geometry, properties, id, and type. The data source is AdV SmartMapping, whose vector model documentation is linked by the project.

Other wrappers expose formats determined by their sources. Bundesanzeiger returns report text indexed by descriptive report titles. Lebensmittelwarnung returns dictionaries containing fields such as id, guid, pubDate, title, manufacturer, warning, and affectedStates. VERENA returns position dictionaries containing school and employment fields such as school_id, desc, replacement_job_title, subjects, comments, and duration.

The Autobahn section differs because it wraps an auto-generated API client. The example imports default_api, creates DefaultApi, calls list_autobahnen, and can request one charging station by a station identifier. It also handles autobahn.ApiException. This split shows that deutschland contains both hand-oriented wrappers and generated clients. Consumers should not assume identical retry policies, exception types, authentication behavior, or data models across modules.

Installation and a first Lebensmittelwarnung query

The project documents installation from PyPI. The README states support for Python 3.9 through 3.12 and says the project is tested on Linux, macOS, and Windows. In an environment using one of those supported Python versions, install the package from PyPI with:

pip install deutschland

The first documented use below searches the federal food warning service for the content type lebensmittel and the region berlin. The result shown in the README is a list of warning dictionaries, so print that list after the call.

from deutschland.lebensmittelwarnung import Lebensmittelwarnung

lw = Lebensmittelwarnung()
data = lw.get("lebensmittel", "berlin")
print(data)

A returned record can contain a warning title, manufacturer, warning reason, affected states, publication date, and a public detail URL. The exact records are controlled by the upstream service, so the README output is an example rather than a fixed expected result.

For development, pyproject.toml identifies Poetry as the packaging tool, while the README requires Poetry version >=1.2.0. It does not provide a complete clone-and-install development command. Contributors therefore need the repository's CI and dependency files to reproduce the full development environment rather than extrapolating commands that are not documented.

Geographic queries, report search, and teaching positions

The Geo module is useful when an application needs features inside a rectangular Berlin area. The documented call passes two coordinate pairs in this order: top right, then bottom left.

from deutschland.geo import Geo

geo = Geo()
data = geo.fetch(
    [52.530116236589244, 13.426532801586827],
    [52.50876180448243, 13.359631043007212],
)
print(data["Adresse"][0])

The example output is a GeoJSON-style feature for Holzmarktstraße 55 in Berlin Mitte. Calling data.keys() instead reveals the feature categories returned for the requested area. The detailed vector model documentation is linked from the README, which is important because the package returns several geometry and attribute categories rather than a single address list.

Company-report search has a different query surface. This call sends Deutsche Bahn AG to the Bundesanzeiger wrapper:

from deutschland.bundesanzeiger import Bundesanzeiger

ba = Bundesanzeiger()
data = ba.get_reports("Deutsche Bahn AG")
print(data.keys())

The returned dictionary is keyed by report descriptions, including annual and consolidated financial report text. The README credits a machine learning model with supporting this implementation, and pyproject.toml includes src/deutschland/bundesanzeiger/assets/model.onnx in the distribution.

For substitute teaching positions, the documented VERENA call has no arguments:

from deutschland.verena import Verena

v = Verena()
data = v.get()
print(data)

Its example output represents positions with school, subject, duration, and comment data. Because the README points to deutschland/verena/example.md for a full example rather than defining the entire schema in the main document, production code should inspect the package example and upstream service documentation before depending on every field.

Package boundaries, upstream changes, and direct-service alternatives

The clearest limitation is that availability and schema stability remain tied to external services. The README explicitly says Presseportal is unavailable because its API changed. That statement is direct evidence that adding a method to this Python package does not insulate users from upstream API changes. Generated clients and bespoke wrappers can also differ in exception handling, configuration, and response shape.

The package is not a mirror of every German government dataset. Handelsregister code has moved to bundesAPI/handelsregister, while supported modules cover a selected set of sources. Documentation coverage is uneven. Geo and Lebensmittelwarnung receive basic examples in the README, and VERENA points to a local example file. Several generated clients primarily link to separate documentation under docs. The main README does not consistently document authentication, quotas, caching, retry behavior, or rate limits.

A real alternative is to call the upstream service directly with requests and parse its response in application code. That avoids installing the full deutschland dependency set and gives direct control over HTTP headers, authentication, caching, retries, and parsing. The trade-off is that the application must implement those details for every service. deutschland reduces that work for supported modules and packages an ONNX asset plus several dependencies, but it does not replace service-specific configuration.

Another alternative is project-specific extraction. For Handelsregister work, the project directs users to the dedicated bundesAPI/handelsregister repository instead of relying on this umbrella package. For a single source with strict compliance or latency needs, a focused integration may also be easier to audit than importing a package containing clients for unrelated domains.

Release cadence, dependency cost, and Apache-2.0 use

The repository is not archived. Its last push was on 2026-04-28, while the newest listed release is 0.4.2 from 2024-06-18. The two dates should not be treated as the same maintenance signal: repository activity continued after the last listed release, but the README and package version still identify release 0.4.2. Neither the README nor the release list provides a publication schedule or an explanation for the gap.

Installation also brings a substantial transitive dependency set. pyproject.toml lists requests, dateparser, beautifulsoup4, more-itertools, numpy, pillow, mapbox-vector-tile, pandas, shapely, lxml, and onnxruntime, along with numerous de-* packages for generated or service integrations. Python is constrained to >=3.9,<4. Some dependencies use version markers for different interpreter versions, and numpy and pandas select different constraints below and at Python 3.12. These details matter when adopting the package into an application with a strict dependency policy or an existing geospatial stack.

The project is licensed under Apache-2.0. That permits use and modification under the license's conditions, including preserving required notices and examining its provisions. This is a project-specific summary, not legal advice. The license covers the package code, while access to each upstream public service remains subject to that service's own terms and technical requirements.

Editorial conclusion

Adopt deutschland when an application needs several supported German public datasets and accepts the package's per-service wrappers, Python range, and dependency footprint. Do not treat it as a complete registry of German government data or as a stable abstraction over every upstream API. Before adoption, verify the first service your application needs, including its documented authentication requirements, response structure, upstream availability, and behavior when that service changes.

Frequently asked questions

Official sources

1. bundesAPI/deutschland on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases