Abgeordnetenwatch API Dokumentation

Sämtliche Daten sind bei uns in eigenen Entitäten definiert. So ist ein Parlament eine eigene Entität mit eigenen Feldern, ebenso die Parlamentsperiode oder der Politiker. Für alle Entitäten gibt es API-Pfade, über welche alle diese Entitäten abgerufen werden können. Welche Entitäten es gibt, erläutern wir hier. Ein Sonderfall sind Kandidaturen und Mandate.

Diese Pfade geben alle Entitäten eines bestimmten Typs zurück. Um nur eine bestimmte Entität zu bekommen, kann der Pfad mit der entsprechenden Id aufgerufen werden. So hat der Bundestag z.B. die Id 5, die 19.Legisltaurperiode des Bundestags ist eine eigenständige Entität vom Typ ParliamentPeriod, sie hat die Id 111.

Kleiner Tipp: Auf vielen unserer Seiten befindet sich ein "OpenData" Button, in dem man die Id für die jeweilige Entität und hilfreiche API-Pfade herausfinden kann.

Die Listen der Entitäten lassen sich filtern, das Beispiel zeigt, wie man alle Wahlperioden des Bundestags abrufen kann. Der Name und der Wert des Filters wird dazu als URL-Parameter an den API-Pfad angehängt. Grundsätzlich können alle Felder einer Entität für die Filterung verwendet werden, teilweise bieten wir noch spezielle Filter an, die kompliziertere Abfragen ermöglichen. Welche Filter möglich sind, erläutern wir bei der Dokumentation der einzelnen Entitäten.

Statt einer einfachen "ist gleich" Abfrage sind auch ein paar andere Operatoren für die Filter möglich. Der Operator wird dazu nach dem Feld- oder Filternamen in eckige Klammern geschrieben. Erlaubte Operatoren sind:

• eq - "equal", ist der Standard-Operator "="
• gt - "greater than", entspricht ">"
• gte - "greater than equal", entspricht ">="
• lt - "less than", entspricht "<"
• lte - "less than equal", entspricht "<="
• ne - "not equal", entspricht "<>" oder "!="
• sw - "STARTS_WITH"
• cn - "CONTAINS"
• ew - "ENDS_WITH"
• in - "IN". Der Wert des Parameters muss als Array definiert werden, siehe Beispiel
• notin - "NOT IN". Der Wert des Parameters muss als Array definiert werden, siehe Beispiel

Zahlreiche Entitäten referenzieren auf andere Entitäten und werden so mit Daten angereichert. Zum Beispiel referenziert ein Mandat auf eine:n Politiker:in, im Feld "politician". Grundsätzlich lassen sich alle Listen nach diesen Referenzen filtern, indem die Id einer referenzierten Entität verwendet wird: politician=123 filtert nach einer Entität mit der Id 123, die im Feld "politician" referenziert ist.

Die API erlaubt es nun, die Felder aus dieser referenzierten Entität zur Filterung zu nutzen. Dies erfolgt, indem dem Referenzfeld-Namen in eckigen Klammern entity.field_name angehängt wird, wobei feld_name der Name des Feldes in der referenzierten Entität ist. Um z.B. nun alle Mandate von weiblichen Abgeordneten zu bekommen, könnte als Filter politician[entity.sex]=f abgehängt werden.

Diese Referenzierungen lassen sich auch verketten: So referenziert die Politician Entität wiederum selbst auf eine Partei - so lassen sich die Mandate nach allen Politikern filtern, die einer Partei mit einem bestimmten Namen angehören: politician[entity.party.entity.name]=Name der Partei

Dies lässt sich darüber hinaus mit den Filter-Operatoren verbinden, siehe das dritte Beispiel, in dem nach Politikern gesucht wird, die einer Partei angehören, in deren Namen das Wort "sozial" vorkommt.

Die Anzahl der zurückgegebene Entitäten ist standardmäßig auf 100 beschränkt. Mit dem URL-Parameter "range_end" lässt sich die Anzahl der zurückgegebenen Ergebnisse auf einen beliebigen Wert (max. 1.000) festlegen. Mit "range_start" lässt sich festlegen, ab dem wie vielten Element die Ergebnisse zurückgegeben werden sollen (Standard ist 0).

Zudem erlaubt die API das Abrufen der Ergebnisse Seite für Seite: mit dem URL-Parameter "page" lässt sich eine definierte Seite der Ergebnisliste zurückgeben, mit "pager_limit" legt man fest, wie viele Ergebnisse pro Seite zurückgegeben werden sollen (Standard ist 100, max. 1.000).

Grundsätzlich kann nach jedem Feld einer Entität sortiert werden. Das Feld wird mit dem URL-Parameter "sort_by" festgelegt, als Sortierreihenfolge ist "absteigend" (desc) vordefifniert. Die Reihenfolge kann zu aufsteigend geändert werden: "sort_direction=asc".

Unser Datenmodell besteht aus einer Vielzahl von Entitäten. So sind bei Abstimmungen z.B. die einzelnen Votes/Stimmen in eigenen Entitäten gespeichert. Um relevante Daten zu einer Entität leichter zu erhalten, gibt es die "related_data". Bei jedem API-Request kann man sich mit dem Parameter "?related_data=show_information" anzeigen lassen, welche ergänzenden Daten es gibt. Hier werden dann zwei API-Pfade zum Abruf dieser Daten angezeigt: einer zu einer vorgefilterten Liste der Entitäten, die dann auch entsprechend der zur Verfügung stehenden Felder dieser Entitäten weiter gefiltert werden kann. Der andere API-Pfad ist der Aufruf einer einzelnen Entität (z.B. einer Abstimmung / Poll), in den die einzelnen Votes/Stimmen hinzugefügt werden können.

Um diese ergänzenden Daten mit in die API-Response hinzuzufügen, fügt man dem API-Aufruf den Parameter "?related_data=" mit der jeweiligen Bezeichnung hinzu. Die Liste der hinzugefügten Daten ist nicht filterbar und stets begrenzt auf maximal 1.000 Entitäten.