GENESIS, CSV und Co.

Inhalt:

1. Grundsätzliches Vorgehen
2. Daten herunterladen und weiterverwenden („Flat‑File‑CSV“)
3. Automatisierter Zugriff auf die GENESIS-API („Webservice“)

Hintergrund

GENESIS, das ist eine Software-Plattform, über die in Deutschland amtliche Statistiken veröffentlicht werden. Die Software wird von den statistischen Ämtern selbst entwickelt und dazu verwendet, verschiedene Datenportale zu betreiben. Dazu gehören beispielsweise das offizielle Statistikportal des Statistischen Bundesamts und die Regionaldatenbank Deutschland, ein Statistikportal, auf dem Daten zu Regionen veröffentlicht werden – also zu Bundesländern, Landkreisen, Städten und Gemeinden. Außerdem werden die Ergebnisse des Zensus über ein GENESIS-Portal veröffentlicht, die Zensus-Datenbank.

Diesen offiziellen Statistikportalen haftete lange ein zweifelhafter Ruf an. Denn sie waren langsam, unübersichtlich und insgesamt nicht sehr nützlich für diejenigen, die diese Daten tatsächlich verwenden wollten, beispielsweise um eigene Grafiken oder Analysen zu erstellen. Das ist auch der Grund, warum das Projekt Datenguide existiert. Unter diesem Namen haben wir seit 2018 an Open-Source-Tools gearbeitet, die es einfacher machen sollten, Daten aus GENESIS-Portalen herunterzuladen und weiter mit ihnen zu arbeiten.

Doch in den letzten Jahren hat sich einiges getan. Die Statistischen Ämter haben Feedback und Kritik ernst genommen und die GENESIS-Plattform kontinuierlich weiterentwickelt. Eine komplette Überarbeitung der Benutzeroberfläche kann aktuell als Beta-Version getestet werden. Neben der verbesserten Benutzerführung gibt es auch Veränderungen auf technischer Seite. Seit einiger Zeit existiert eine API, über die auf die Datensätze zugegriffen werden kann (die „GENESIS-Webservice-Schnittstelle“), und ein neues Tabellenformat („Flat-File-CSV“) das es einfacher machen soll, die Daten weiter zu verwenden. Grund genug, GENESIS eine zweite Chance zu geben.

Im Rest dieses Artikels erklären wir, was du brauchst um Daten aus GENESIS auszuwerten und zu visualisieren, zum Beispiel in einer Umgebung wie Jupyter oder Observable.

Grundsätzliches Vorgehen

Wenn du nur einige wenige Datensätze nutzen möchtest, kannst du sie direkt über die Web-Oberfläche der verschiedenen GENESIS-Datenbanken herunterladen. Die Daten werden dort in Tabellenform angezeigt und können als Excel- oder CSV-Datei abgerufen werden.

Wenn du dagegen regelmäßig Daten aus GENESIS verwendest, oder wenn du größere Datenmengen automatisiert weiterverarbeiten möchtest, solltest du die GENESIS-API („Webservice“) nutzen. Diese API ermöglicht es, die Daten direkt mit einer Programmiersprache wie R oder Python abzurufen.

Daten herunterladen und weiterverwenden („Flat‑File‑CSV“)

Für diese Anleitung gehen wir davon aus, dass du einen Datensatz herunterladen möchtest, um ihn dann mit einem Tool wie Observable, Jupyter oder R zu verwenden. Die Schritte sind:

1. Finde eine Tabelle in einem der GENESIS-Datenportale
2. Lade die Tabelle im Format „Flat-File-CSV“ herunter
3. Lese die CSV-Datei im korrekten Format ein (z.B. Zeichenkodierung, Zahlenformat)
4. Bringe die Tabelle in eine Form, mit der du weiterarbeiten kannst
5. Visualisiere die Daten oder nutze sie in deiner Analyse

Wir verwenden in diesem Beispiel die Regionaldatenbank, aber das grundsätzliche Vorgehen ist für alle GENESIS-Portale gleich.

Herunterladen eines Datensatzes

In der Regionaldatenbank findest du eine Vielzahl von regionalen Statistiken zu verschiedenen Themen. Jede Statistik besteht aus mehreren Tabellen. Wenn du eine Tabelle gefunden hast, die du verwenden möchtest, kannst du sie vor dem Download konfigurieren, zum Beispiel indem du bestimmte Regionen oder Zeiträume auswählst. In vielen Fällen kannst du die Daten dann direkt herunterladen. Bei umfangreichen Datensätzen musst du dich allerdings anmelden, bevor du die Daten abfragen kannst. Die Registrierung ist kostenlos.

Für die Verwendung der Daten in eigenen Grafiken oder Analysen ist in der Regel das Format Flat („Flat-File-CSV“) am geeignetsten. In diesem Format sind die Tabellen nicht verschachtelt und jede Spalte hat einen eindeutigen Titel in der ersten Zeile der Tabelle. Dadurch ist es einfacher, die Daten in Tools wie Observable, Jupyter, oder R zu laden.

Einlesen der Daten

Nach dem Download der CSV-Datei lädst du sie in deiner Programmierumgebung. Das erste Problem: Im Gegensatz zum Rest des modernen Internets verwendet GENESIS nicht die Zeichenkodierung utf-8, den de-facto-Standard in modernen APIs. Stattdessen setzen die statistischen Ämter auf die Zeichenkodierung windows-1252. Damit soll die Kompatibilität mit Software von Microsoft verbessert werden. Leider führt das auch dazu, dass Umlaute und andere Sonderzeichen in vielen anderen Tools nicht richtig dargestellt werden. Um solche Probleme zu vermeiden, musst du die Datei mit der korrekten Zeichenkodierung laden – also mit windows-1252.

Außerdem musst du darauf achten, dass die Spalten korrekt getrennt sind und Zahlen richtig eingelesen werden. GENESIS verwendet ein deutsches Zahlenformat, mit Kommas als Dezimaltrenner, und als CSV-Trennzeichen das Semikolon (;). Diese Einstellungen musst du beim Einlesen der Daten vornehmen, zum Beispiel in Python mit Hilfe von pandas.read_csv:

# Einlesen der Daten mit pandas (vereinfachtes Beispiel)
pd.read_csv(csv_input, delimiter=';', decimal=",")

Danach kannst du die Daten transformieren, um sie in das Format zu bringen, das du für deine Auswertung oder Visualisierung benötigst. In diesem Observable-Notebook findest du ein komplettes Beispiel dafür, wie du Daten aus der Regionaldatenbank in Observable einlesen und visualisieren kannst. Ein Beispiel für Python findest du in dem Jupyter-Notebook, das am Ende des nächsten Kapitels verlinkt ist.

Automatisierter Zugriff auf die GENESIS-API („Webservice“)

Wenn du regelmäßig Daten aus GENESIS herunterlädst, oder wenn du die Daten automatisiert weiterverarbeiten möchtest, solltest du die GENESIS-API („Webservice“) nutzen. Diese API ermöglicht es, Datensätze direkt mit einer Programmiersprache wie Python zu durchsuchen und herunterzuladen. Für die Nutzung der GENESIS-API ist eine Registrierung auf dem jeweiligen Datenportal notwendig.

Die GENESIS-API ist eine REST-Schnittstelle, die Antworten im JSON-Format zurückgibt. Allerdings sind die eigentlichen Daten, die über die API abgefragt werden, nicht mittels JSON kodiert, sondern werden in den gleichen Formaten zurückgegeben wie in der oben beschriebenen Web-Oberfläche, zum Beispiel als „Flat-File-CSV“. JSON wird nur für Metadaten verwendet. Der Zugriff auf die Inhalte der Tabellen erfolgt auf die gleiche Art und Weise, die du auch für den manuellen Download der Daten verwenden würdest.

Über die API kannst du, wie in der Web-Oberfläche, nach Datensätzen suchen, sie konfigurieren und herunterladen. Hier ein einfaches Beispiel, wie du mit Python Daten aus der Regionaldatenbank herunterladen kannst:

# Suche nach Statistiken für den Suchbegriff „Inflation“
search = requests.get(BASE_URL + 'find/find', params={
    'username': USERNAME,
    'password': PASSWORD,
    'language': 'de',
    'term': 'Inflation'
})

# Anzeigen der Suchergebnisse als DataFrame:
pd.DataFrame.from_dict(search_results['Tables']).head(5)

#     Code        Content
# =============================================================
# 0 61111-0001  Verbraucherpreisindex: Deutschland, Jahre
# 1 61111-0002  Verbraucherpreisindex: Deutschland, Monate
# 2 61111-0003  Verbraucherpreisindex: Deutschland, Jahre, ...
# 3 61111-0004  Verbraucherpreisindex: Deutschland, Monate, ...
# 4 61111-0005  Verbraucherpreisindex: Deutschland, Jahre, ...
# 5 61111-0006  Verbraucherpreisindex: Deutschland, Monate, ...

Anhand der Suchergebnisse kannst du den Code der Tabelle ermitteln, die du herunterladen möchtest. Das folgende Beispiel zeigt, wie du die Daten der Tabelle im Flat-File-CSV (ffcsv) herunterladen kannst. Die Weiterverarbeitung der Daten erfolgt dann wie im vorherigen Abschnitt beschrieben.

# Herunterladen eines Datensatzes aus der Regionaldatenbank Deutschland
response = requests.get(BASE_URL + 'data/tablefile', params={
    'username': USERNAME,
    'password': PASSWORD,
    'name': '61111-0001',
    'area': 'all',
    'format': 'ffcsv', # Flat-File-CSV
    'language': 'de'
})
print(response.text)

Das Komplette Beispiel, inklusive der Authentifizierung und der Visualisierung der heruntergeladenen Daten, findest du in diesem Jupyter-Notebook. Für Nutzer:innen von R und Python gibt es außerdem inoffizielle Bibliotheken, die den Zugriff auf die GENESIS-API erleichtern. Das Python-Paket pystatis und das R-Paket restatis bieten Funktionen, um Daten aus GENESIS herunterzuladen und weiterzuverarbeiten. Der Vorteil dieser Pakete ist, dass sie die Authentifizierung und die Aufbereitung der Daten für dich übernehmen.

Fazit

Die GENESIS-Plattform wurde in den letzten Jahren deutlich verbessert. Die Datenportale sind übersichtlicher und bieten bessere Möglichkeiten, die Daten weiterzuverwenden. Die Einführung der REST-API und des Tabellenformats „Flat-File-CSV“ sind wichtige Schritte, um die Daten der amtlichen Statistik besser zugänglich zu machen.

Auch wenn die GENESIS-Portale nicht perfekt sind, empfehlen wir inzwischen die Nutzung der offiziellen Schnittstellen. Die Daten sind dort aktuell und stammen direkt aus ihrer offiziellen Quelle. Das ist ein großer Vorteil gegenüber alternativen Datenquellen wie der Datenguide-API, die wir zum 15. Juni 2024 abschalten werden.