Abgeordnetenwatch API Response

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: {},
},
{},
{},
{},
{},
{},
]

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: {...}
  }
}