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 - kann "ok", "warning" oder "error" sein. Hinweise zu "warning" und "error" finden sich dann in der status_message, siehe nächster Punkt.
  • status_message - bei Status "ok" in der Regel leer, bei Status "error" die entsprechende Fehlermeldung. Ist der Status "warning" sind alle Warnungen mit einer Pipe (|) getrennt in einem String ausgegeben.
  • 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". Ist der Status der Response error (siehe oben), ist der data-Block leer.

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