Abgeordnetenwatch API Response
- Der meta-Block
- Der data-Block
- Ergänzende Daten: related_data
- Standard-Felder einzelner Entitäten
- Referenzierte Entitäten
Der meta
-Block
Die Response der API enthält immer einen Block meta
und einen Block data
.
Im meta
-Block sind folgende Felder zu finden:
- abgeordnetenwatch_api - ein Array mit mehreren Feldern, welche Informationen zur API generell beinhalten:
- "version" - die aktuelle API-Version
- "changelog" - ein Link zum Changelog für die aktuelle API-Version
- "licence" - die Bezeichnung der Lizenz, unter der die Daten zur Verfügung gestellt werden. Aktuell: CC0 1.0
- "licence_link" - ein Link zur Beschreibung der Lizenz: https://creativecommons.org/publicdomain/zero/1.0/deed.de
- "documentation" - ein Link zur Dokumentation für die aktuell aufgerufene Entität
- status - ist entweder "ok" oder "error".
- status_message - bei Status "ok" in der Regel leer, bei Status "error" die entsprechende Fehlermeldung.
- result - Informationen zu dem zurückgegebenen Werten in
data
.- count - Anzahl der Ergebnisse in der API-Response.
- total - Anzahl aller Ergebnisse. Die Anzahl der Ergebnisse pro Response ist beschränkt, dieser Wert zeigt an, wie viele Ergebnisse es ohne Beschränkung wären.
- range_start / range_end - siehe "API Grundlagen". Nur enthalten, wenn kein
page
-Parameter gesetzt ist - page / results_per_page - siehe "API Grundlagen". Nur enthalten, wenn der
page
-Parameter gesetzt ist
{
meta: {
abgeordnetenwatch_api: {
version: "2.0",
changelog: "https://www.abgeordnetenwatch.de/api/version-changelog/aktuell",
licence: "CC0 1.0",
licence_link: "https://creativecommons.org/publicdomain/zero/1.0/deed.de",
documentation: "https://www.abgeordnetenwatch.de/api/entitaeten/parliament"
},
status: "ok",
status_message: "",
result: {
count: 18,
total: 18,
range_start: 0,
range_end: 100
}
},
data: [] / {}
Der data
-Block
Der data
-Block beinhaltet die eigentlichen Daten. Entweder ist data
ein Array von Entitäten, also eine Liste, oder es ist direkt das Objekt der einzelnen Entität, siehe "API Grundlagen"
Einzelne Entität
data: {
id: "60",
entity_type: "parliament",
label: "Hamburg",
api_path: "https://www.abgeordnetenwatch.de/api/v2/parliaments/60",
url: "https://www.abgeordnetenwatch.de/hamburg",
label_external_long: "Hamburg",
current_project: {},
}
Liste von Entitäten
data: [
{
id: "60",
entity_type: "parliament",
label: "Hamburg",
api_path: "https://www.abgeordnetenwatch.de/api/v2/parliaments/60",
url: "https://www.abgeordnetenwatch.de/hamburg",
label_external_long: "Hamburg",
current_project: {},
},
{
id: "63",
entity_type: "parliament",
label: "Baden-Württemberg",
api_path: "https://www.abgeordnetenwatch.de/api/v2/parliaments/63",
url: "https://www.abgeordnetenwatch.de/baden-wurttemberg",
label_external_long: "Baden-Württemberg",
current_project: {},
},
{},
{},
{},
{},
{},
]
Ergänzende Daten: related_data
Da sich in unserem Datenmodell die Daten auf verschiedene Entitäten verteilen, bieten wir hier einige Hinweise auf hilfreiche API-Pfade. So kann man sich bei einem Parlament einen Link zur Liste aller Legislatur-Perioden für dieses Parlament anzeigen lassen, bei einem Politiker findet man Links zu den Mandaten und Kandidaturen des Politikers. Die verlinkten API-Pfade beinhalten dann schon die benötigten Filter. Diese ergänzenden Informationen kann man sich mit dem Parameter related_data=show_information
anzeigen lassen. Hier finden sich dann zwei Pfade:
api_path
- der Pfad, über den die ergänzenden Daten aufgefrufen und weiter gefiltert werden können.api_path_include
- der Pfad, über den die ergänzenden Daten direkt in die API-Response für eine Entität integriert werden können.
Die Integration dieser ergänzenden Daten erfolgt durch den Parameter ?related-data=
, dem die Bezeichnung der ergänzenden Daten angehängt wird, im Beispiel "legislatures". Bei Aufruf des in api_path_include
angegebenen Pfades werden dann die Daten des Parlaments sowie alle damit verbundenen Parlamentsperioden vom Typ "Legislatur" angezeigt.
Beschränkungen der integrierten ergänzenden Daten: die Daten sind nicht filter- oder sortierbar, die Menge der integrierten Entitäten ist auf 1.000 beschränkt.
Anzeige related_data
durch related_data=show_information
{
id: "60",
entity_type: "parliament",
label: "Hamburg",
api_path: "https://www.abgeordnetenwatch.de/api/v2/parliaments/60",
abgeordnetenwatch_url: "https://www.abgeordnetenwatch.de/hamburg",
related_data: {
legislatures: {
meta: {
description: "List legislatures for the parliament"
},
api_path: "https://www.abgeordnetenwatch.de/api/v2/parliament-periods?parliament=60&type=legislature"
}
}
}
Integration von related_data
durch related_data=legislatures
data: [
{
id: "60",
entity_type: "parliament",
label: "Hamburg",
api_path: "https://www.abgeordnetenwatch.de/api/v2/parliaments/60",
url: "https://www.abgeordnetenwatch.de/hamburg",
label_external_long: "Hamburg",
current_project: {},
related_data: {
legislatures: {
meta: {
description: "List legislatures for the parliament"
},
api_path: "https://www.abgeordnetenwatch.de/api/v2/parliament-periods?parliament=60&type=legislature"
}
}
}
]
Standard-Felder einzelner Entitäten
Die einzelnen Entitäten unterscheiden sich in den unterschiedlichen Feldern und Filtern, die zur Verfügung stehen. Grundsätzlich haben sie aber alle folgende Felder:
- id - die Id der Entität bei Abgeordnetenwatch.de.
- entity_type - die Id des Entitätstyps
- label - die Bezeichnung der Entität
- api_url - der API-Pfad, unter dem die einzelne Entität aufgerufen werden kann.
- abgeordnetenwatch_url - die URL zur Detailansicht für diese Entität auf abgeordnetenwatch.de
{
id: "60",
entity_type: "parliament",
label: "Hamburg",
api_path: "https://www.abgeordnetenwatch.de/api/v2/parliaments/60",
abgeordnetenwatch_url: "https://www.abgeordnetenwatch.de/hamburg",
related_data: {
legislatures: {
meta: {
description: "List legislatures for the parliament"
},
api_path: "https://www.abgeordnetenwatch.de/api/v2/parliament-periods?parliament=60&type=legislature"
}
}
}
Referenzierte Entitäten
Um z.B. eine Kandidatur einem Politiker zuzuweisen, wird in der Entität vom Typ "candidacy_mandate" eine Referenz auf den jeweiligen Politiker definiert. In der API werden referenzierte Entitäten mit den Standard-Feldern mit ausgeben, womit es möglich ist, durch einen weiteren API-Aufruf die Detail-Daten dieser referenzierten Entitäten abzurufen. Das Beispiel zeigt die Referenz in der Kandidatur/ dem Mandat auf den Politiker.
{
id: "123",
entity_type: "candidacy_mandate",
label: "Muster Muster (Musterparlamemt)",
api_url: "https://www.abgeordnetenwatch.de/api/v2/candidacies-mandates/123",
type: "mandate",
politician: {
id: "345",
entity_type: "politician",
label: "Muster Muster",
api_url: "https://www.abgeordnetenwatch.de/api/v2/politicians/345",
related_data: {...}
}
}