Mit sogenannten API-Schnittstellen ist es möglich zwischen verschiedenen Computerprogrammen oder Systemen zu interagieren. Eine solche Schnittstelle kann u. a. genutzt werden, um Daten aus Online-Befragungen in Echtzeit auszuwerten. Wie dies geht, soll in diesem Blogbeitrag mit der Software LimeSurvey und R erklärt werden.

Inhaltsverzeichnis des Beitrags Verbergen
1 Was ist eine API?
2 LimeSurvey und R
3 API in LimeSurvey aktivieren
4 API Zugriff in R einrichten
5 Fazit

Was ist eine API?

API ist die Abkürzung für Application Programming Interface und stellt verschiedene Befehle und Funktionen zur Verfügung, mit denen verschiedene Systeme miteinander interagieren und kommunizieren können.

Eine solche API-Schnittstelle kann auch genutzt werden, um Daten zwischen Programmen und Systemen auszutauschen und zu verarbeiten. Im Rahmen der Datenauswertung kann man sich dies zunutze machen, um den Prozess des Reportings weiter zu automatisieren. So kann durch die direkte Abfrage des aktuellen Datensatzes in der Online-Befragungs-Lösung das manuelle Exportieren von Daten entfallen.

LimeSurvey und R

R ist eine freie Programmiersprache zur statistischen Datenanalyse und wird unter einer Open-Source-Lizenz veröffentlicht. Der große Vorteil von R ist, dass die Grundsoftware (“base”) mit Paketen erweitert werden kann. Neben Paketen zu bestimmten statistischen Verfahren, gibt es hier auch Pakete, die einen Zugang zu API-Schnittstellen zur Verfügung stellen. Für die Arbeit mit R kann ich übrigens das Programm RStudio empfehlen, dass die Arbeit in vielerlei Hinsicht erleichtert.

LimeSurvey ist eine Online-Befragungs-Lösung, die ebenfalls unter einer Open-Source-Lizenz veröffentlicht wird. Dies bedeutet, dass die Software kostenfrei bezogen und auf einem eigenen Webserver installiert werden kann. Neben dieser “Community-Version” gibt es auch gehostete Versionen, die man gegen eine monatliche oder jährliche Gebühr buchen kann. Im Funktionsumfang von LimeSurvey ist bereits eine API-Schnittstelle enthalten, die allerdings vor der ersten Nutzung noch aktiviert werden muss.

API in LimeSurvey aktivieren

Vor der ersten Nutzung der LimeSurvey-API muss diese in den Einstellungen aktiviert werden. Hierzu muss man sich als Administrator in LimeSurvey anmelden und dann unter Konfiguration die globalen Einstellungen auswählen. Wählt man danach den Reiter Schnittstellen aus, kommt folgender Dialog:

Dialog zur Aktivierung der API in Limeusrvey
Aktivierung der API in LimeSurvey

Um einen Zugriff auf die API zu ermöglichen, muss unter dem Eintrag “RPC-Interface aktiviert:” der Eintrag “JSON-RPC” ausgewählt werden. Darunter wird die URL aufgeführt, mit der die API angesprochen werden kann. Diese wird dann später beim Zugriff durch R benötigt. Im Eintrag “API veröffentlichen unter /admin/remotecontrol” kann die Eigenschaft “Aus” ausgewählt werden. Die Änderungen an den Einstellungen müssen gespeichert werden. Danach ist die LimeSurvey API erreichbar. Sollte die API nicht mehr genutzt werden, empfiehlt es sich natürlich die Funktion in den Einstellungen wieder zu deaktivieren.

API Zugriff in R einrichten

Um in R auf die Daten aus LimeSurvey zugreifen zu können, muss eine Verbindung mit der LimeSurvey-API-Schnittstelle aufgebaut werden. Dies geht mit dem Paket limer. Da das Paket noch nicht auf CRAN veröffentlicht ist, erfolgt die Installation über github:

install.packages(devtools)
devtools::install_github("cloudyr/limer")Code language: R (r)

Die erste Zeile im dargestellten Code muss nur ausgeführt werden, wenn das Paket “devtools” noch nicht installiert ist. Dieses wird benötigt, um Pakete von github zu installieren.

Nach der Installation kann man das Paket laden und über drei Befehle den Link zur API, den Benutzername und das Kennwort von LimeSurvey hinterlegen:

library(limer)
options(lime_api = 'https://deine-domain.de/evtl-ordner/admin/remotecontrol')
options(lime_username = 'benutzername_hier')
options(lime_password = 'kennwort_hier')Code language: R (r)
Achtung: Bei den Optionen muss der Benutzername und das Kennwort des LimeSurvey-Zugangs hinterlegt werden. Wird dies in einer R-Skript-Datei abgespeichert, sollte diese nicht weitergegeben werden.

Wurden die Einstellungen gesetzt, erfolgt der Abruf des Datensatzes. Hierzu muss die ID der Umfrage im System bekannt sein. In LimeSurvey wird diese in der Umfragenliste in der Spalte “Umfrage ID” aufgeführt. Mithilfe dieser Nummer und folgenden Code, kann man dann die Daten in R laden. Zuvor muss aber ein Session-Key angefordert werden, um einen Zugriff auf LimeSurvey aufbauen zu können (im Beispiel wird als Umfrage ID die 12345 verwendet):

#Session-Key anfordern
get_session_key()
# Daten in R laden
datenBefragung <- get_responses(12345)  Code language: R (r)

Wird der Code ausgeführt, steht danach in R das Objekt “datenBefragung” als Datensatz (data frame) zur Verfügung. Allerdings werden mit der oben dargestellten Funktion die Antwortlabels in R übernommen und nicht die Antwortcodes. Also z. B. männlich anstatt dem hinterlegten Code 1. Um dies anzupassen, muss die Funktion get_responses() erweitert werden:

datenBefragung <- get_responses(iSurveyID = 12345,
                                sCompletionStatus = "completed_responses",
                                sHeadingType = "code",
                                sResponseType = "code")Code language: R (r)

In der dargestellten get_responses()-Funktion wird folgendes festgelegt:

  • iSurveyID: Es werden die Daten der Umfrage mit der ID 12345 aus LimeSurvey abgerufen.
  • sCompletionStatus: Es wird festgelegt, dass nur komplette Datensätze geladen werden.
  • Es werden die Variablen- (sHeadingType) und Antwortlabels (sResponseType) exportiert. Dies wird in der Funktion mit der Bezeichnung “code” definiert.

Mit dem Objekt “datenBefragung”, das in R geladen wurde, kann dann ganz normal weitergearbeitet werden. Wird der dargestellte Code am Anfang von einem Auswertungsskript oder eine Markdown-Datei eingefügt, wird immer der aktuelle Datenstand aus der Umfrage in R geladen und für die Auswertung genutzt.

Fazit

Mithilfe einer API-Schnittstelle kann das regelmäßige Reporting von Erhebungen noch weiter automatisiert werden. Durch das Abrufen des aktuellen Datenbestandes aus dem Befragungsprogramm entfällt das manuelle Herunterladen und Einlesen des Datensatzes. Verbunden mit einem reproduzierbaren Reporting in R können somit noch schneller aktuelle Reports von Erhebungen erstellt werden. Auch ist in R mit dem Paket Shiny eine Entwicklung von Dashboards möglich, die beim Starten immer auf den aktuellen Datenbestand zugreifen.

Am Schluss sei noch angemerkt, dass es solche API-Schnittstellen nicht nur in LimeSurvey gibt, sondern auch in anderen Lösungen für Online-Befragungen. So bietet unter anderem auch LamaPoll eine API-Schnittstelle und stellt in der Dokumentation auch den entsprechenden R-Code zur Verfügung, um die Daten über die API in R zu importieren.

Wer noch weitere Online-Befragungs-Lösungen mit einer API-Schnittstelle kennt, kann diese gerne in den Kommentaren zu diesem Beitrag ergänzen.

Gleich weiterlesen...