Datenbank-API für Wahlumfragen als JSON-Datei (Open Data, ODbL)

Wir stellen unsere Datenbank mit Wahlumfragen als API über eine JSON-Datei im Rahmen von Open Data unter der ODC Open Database License (ODC-ODbL) der Allgemeinheit zur Verfügung.

Inhalt der API

Diese JSON-Datei beinhaltet Informationen einer jeden Wahlumfrage über:

  • Parlament, Institut und Auftraggeber
  • Umfrageergebnisse für die einzelnen Parteien
  • Tag der Veröffentlichung
  • Befragungszeitraum und Anzahl der Befragten

Unsere API wird bei Eintragung einer neuen Wahlumfrage in unsere Datenbank automatisch aktualisiert und ist so stets auf dem gleichen Stand wie unsere SQL-Datenbank. Die API enthält Wahlumfragen zu Bundes- und Landtagswahlen ab 2017.

Aufbau der JSON-Datei

Die JSON-Datei setzt sich aus sechs Blöcken zusammen:

  • Database: Informationen über die Datenbank
    • License: lange (Name) und kurze (Shortcut) Bezeichnung der Lizenz mit Adresse der Website (Link)
    • Publisher: Domain unserer Seite
    • Author: Ersteller der Datenbank
    • Last_Update: letzte Aktualisierung der Datenbank (Format DateTime::W3C) / identisch mit dem Inhalt der last_update.txt
  • Parliaments: IDs und Bezeichnungen
    • Shortcut: Bundesland / Bundestag
    • Name: Bezeichnung des Parlaments
    • Election: Bezeichnung der Wahl
  • Institutes: IDs und Bezeichnung der Institute (Name)
  • Taskers: IDs und Bezeichnungen der Auftraggeber (Name)
  • Parties: IDs und Bezeichnungen
    • Shortcut: Abkürzung der Partei
    • Name: vollständige Bezeichnung der Partei
  • Surveys: IDs und Details zu Wahlumfragen
    • Parliament_ID, Institute_ID, Tasker_ID
    • Results: Partei-ID mit Umfrageergebnis
    • Date: Veröffentlichungsdatum (in ISO 8601)
    • Survey_Period: Befragungszeitraum mit Date_Start und Date_End
    • Surveyed_Persons: Anzahl der Befragten

Nutzung der API

Unsere Datenbank mit den einzelnen Wahlumfragen, die über unsere API verfügbar ist, kann im Rahmen der Lizenz ODC-ODbL verwendet werden. Dies setzt insbesondere die Nennung und Verlinkung unserer Seite (dawum.de) sowie die Beibehaltung und Nennung der Lizenz ODC-ODbL voraus.

Datensparsame kompaktere JSON-Datei

Wer nur die jeweils neuesten Wahlumfragen jedes Instituts zu jedem Parlament benötigt, sollte besser die dafür angepasste JSON-Datei unter https://api.dawum.de/newest_surveys.json verwenden, die wesentlich kleiner als die Datei mit allen Wahlumfragen ist und damit auch schneller geladen werden kann.

Einbindung unserer API

Prüfung der Aktualität

Zur einfachen Überprüfung der Aktualität der übertragenen Datenbank auf Ihrem Server mit der aktuellen Version bei DAWUM kann der Wert für Last_Update in Database bei Ihrer kopierten Datenbank mit dem Inhalt der Textdatei unter https://api.dawum.de/last_update.txt abgeglichen werden (siehe Beispiel für PHP).

Python Library

Für die Einbindung der API mit Python ist auf GitHub vom Nutzer lichtbaer eine Python Library mit dem Namen German election poll data (gepd) veröffentlicht worden.

Beispiel für PHP

Beispielsweise lässt sich eine Tabelle über Wahlumfragen durch Erstellen und Aktualisieren einer eigenen JSON-Datei mittels unserer API einfach realisieren. Im Folgenden ein Code-Beispiel für PHP zur Ausgabe unserer Datenbank:

// Auslesen und Aktualisierung der eigenen JSON-Datei $API_File_Last_Update = file_get_contents('https://api.dawum.de/last_update.txt'); $MyFile = 'myfile.json'; // Auslesen der eigenen JSON-Datei if (file_exists($MyFile)) { $MyFile_Content = file_get_contents($MyFile); $PHP_Array = json_decode($MyFile_Content, true); } // Aktualisieren / Neuschreiben sowie (Neu)Auslesen der eigenen JSON-Datei if (!file_exists($MyFile) OR ($PHP_Array['Database']['Last_Update'] != $API_File_Last_Update)) { $API_File_Content = file_get_contents('https://api.dawum.de/'); file_put_contents($MyFile, $API_File_Content); $MyFile_Content = file_get_contents($MyFile); $PHP_Array = json_decode($MyFile_Content, true); } // Sortierung der Parteien (ID) nach den Umfragewerten foreach ($PHP_Array['Surveys'] AS $Surveys) { foreach ($Surveys['Results'] AS $Party_ID => $Result) { $Parties_Sum[$Party_ID] += $Result; $Parties_Count[$Party_ID] += 1; } } // Bildung des Durchschnitts je Partei foreach ($Parties_Sum AS $Party_ID => $Party_Sum) { $Parties_Average[$Party_ID] = ($Party_Sum/$Parties_Count[$Party_ID]); } arsort($Parties_Average); // Ausgabe des Tabellenkopfes echo '<table><thead><td>Datum</td><td>Parlament</td><td>Institut</td><td>Auftraggeber</td>'; foreach ($Parties_Average AS $Party_ID => $Party_Average) { echo '<td title="'.$PHP_Array['Parties'][$Party_ID]['Name'].'">'.$PHP_Array['Parties'][$Party_ID]['Shortcut'].'</td>'; } echo '</thead>'; // Ausgabe des Tabellenkörpers foreach ($PHP_Array['Surveys'] AS $Content) { echo '<tr><td>'.$Content['Date'].'</td><td>'.$PHP_Array['Parliaments'][$Content['Parliament_ID']]['Name'].'</td><td>'.$PHP_Array['Institutes'][$Content['Institute_ID']]['Name'].'</td><td>'.$PHP_Array['Taskers'][$Content['Tasker_ID']]['Name'].'</td>'; // Ausgabe der Parteien/Umfragewerte in der Reihenfolge des Tabellenkopfes foreach ($Parties_Average AS $Party_ID => $Party_Average) { echo '<td>'.$Content['Results'][$Party_ID].'</td>'; } echo '</tr>'; } echo '</table>';

Die Ausgabe dieses Codes kann man sich hier anschauen.

Fragen zur Einbindung

Bei Fragen zur Einbindung unserer API können Sie sich gerne an uns wenden.

API-nutzende Projekte und Apps

Aus unserer API hat bisher insbesondere Henning Tillmann ein iOS-Kurzbefehl erstellt, mithilfe dessen man sich von Siri die aktuellen Umfragewerte ausgeben lassen kann.