Dies ist eine alte Version des Dokuments!
SoSci Survey bietet die Möglichkeit, die erhobenen Daten automatisiert über eine Schnittstelle (API) abzurufen. Einen entsprechenden API-Link erstellen sie unter Erhobene Daten → Datenabruf via API.
Sie können derzeit zwischen 2 Ausgabevarianten wählen:
In beiden Varianten können Sie beim Erstellen des API-Links (mit dem Plus-Symbol rechts oben) festlegen, auf welche Daten der Link Zugriff gewährt und auf welche nicht.
Standardmäßig liefert der API-Link alle erhobenen Daten (entsprechend den im API-Link festgelegten Auswahlkriterien).
Das JSON hat dabei folgende Attribute:
metadata
filter
).errors
data
C
+ Nummer des Datensatzes (CASE) vorliegen.C213
variables
{ "metadata": { "project": "z2018", "datetime": "2018-08-01 22:35:18", "filter": [ "Nur ausgewählte Fälle: CASE 120, 121" ], "language": "ger" }, "data": { "C120": { "CASE": 120, "SERIAL": "H3PVKWVM6H", "QUESTNNR": "short", "MODE": "interview", "STARTED": "2018-03-30 21:16:33", "T109_01": 4, "FINISHED": 1, "Q_VIEWER": 0, "LASTPAGE": 2, "MAXPAGE": 2 }, "C121": { "CASE": 121, "SERIAL": "LSFK1ZX25B", "QUESTNNR": "short", "MODE": "interview", "STARTED": "2018-03-30 21:16:55", "T109_01": 2, "FINISHED": 1, "Q_VIEWER": 0, "LASTPAGE": 2, "MAXPAGE": 2 } } }
Alle Parameter sind optional. Wenn keine weiteren Parameter beim Aufruf des API-Links spezifiziert werden (per GET oder POST), dann werden alle dem Auswahlkriterien des API-Links entsprechenden Fälle abgerufen.
cases
– Fälle (CASE), die abgerufen werden sollen.1,2,5,10-20
.101-
, um alle Fälle ab CASE 101 abzurufen.1-100
erlaubt und der Parameter cases
den Bereich 50-150
abrufen möchte, so werden die Fälle 50 bis 100 abgerufen.none
deaktiviert den Abruf von Daten, wenn z.B. nur die Variablen und/oder Antwortcodes abgerufen werden sollen.vList
– Variablen, die abgerufen werden sollen.vList
angegeben ist, werden nur (!) die angegeben Variablen abgerufen.CASE,AB01_01,AB01_02
.vSkip
wird ignoriert, wenn vList
spezifiziert wurde.vSkip
– einzelne Variablen ausschließen.vSkipTime
– Die Variablen Zur Verweildauer (TIME000) und zur letzten Datenübermittlung (LASTDATA) ausschließen.vQuality
– Qualitätsindikatoren (MISSING, MISSREL, TIME_RSI, DEG_TIME) in den Datensatz aufnehmen.vAddress
– Kontaktdaten von Serienmail-Addressaten (E-Mail, Mobilnummer, UID) in den Datensatz aufnehmen (nur möglich, wenn die Adresseinträge mit dem Datenschutz-Modus „personenbezogen“ importiert wurde).startMin
– Nur Fälle ab diesem Zeitpunkt abrufen.2018-04-01T16:30:30
(das „T“ zwischen Datum und Zeit ist optional, es ist auch ein Leerzeichen möglich).startMax
– Nur Fälle, die bis zu diesem Zeitpunkt begonnen wurden abrufen.changed
– Nur Fälle abrufen, die zuletzt nach diesem Zeitpunkt geändert wurden.changed
angibt, erhält man alle seit dem letzten Abruf geänderten Fälle.infoVariables
– Daten- und Abfrageformat von Variablen ausweisen.infoValues
– Antwortcodes der Variablen ausweisen.infoQuestionText
– Fragetexte zu allen Variablen ausweisen.Wenn der API-Link z.B. lautet:
https://www.soscisurvey.de/PROJEKT/?act=uDywDXaYyNEY
Dann würde folgender Abruf nur die Fälle 120 und 121 liefern und die Variablen zur Verweildauer ausschließen:
https://www.soscisurvey.de/PROJEKT/?act=uDywDXaYyNEY&vSkipTime&cases=120,121
Folgender Aufruf würde nur die Variablen STARTED, AB01, AB02 und AB03_01 liefern und zwar nur für Fälle, bei denen nach dem 1.8.2018, 12 Uhr noch Daten geändert wurden:
https://www.soscisurvey.de/PROJEKT/?act=uDywDXaYyNEY&vList=STARTED,AB01,AB02,AB03_01&changed=2018-08-01T12:00:00
Zum Abruf der Variablen-Labels und Antwortcodes ohne weitere Daten diest der folgende Aufruf:
https://www.soscisurvey.de/PROJEKT/?act=uDywDXaYyNEY&cases=none&infoValues
CSV-Dateien (Comma Separated Values) sind kompatibel mit nahezu jedem Tabellenkalkulations- und Statistik-Programm. Es stehen dieselben Parameter zur Verfügung wie beim JSON-Abruf.
Beim „CSV für Excel“ werden die Daten für den Import in Excel optimiert. Die folgenden Parameter erlauben eine Anpassung des Formats:
decimal
– Festlegen des verwendeten Dezimal-Trennzeichens. Hier sind die Angaben „point“ (Punkt) und „comma“ (Komma) erlaubt. Standardmäßig wird das Dezimaltrennzeichen anhand der Basissprache des Befragungsprojekts festgelegt.missing
– Umgang mit fehlenden Werten, erlaubt sind „code“ (numerischer Code, Standard), „stata“ (Stata-Codes) und „remove“ (Fehlende Werte aus der Tabelle entfernen).encoding
– Dateikodierung, erlaubt sind „utf-16“ (UTF-16 LE für Excel, Standard), „utf-8“ und „iso-8859-1“.
Beim „CSV für R“ werden die Daten so formatiert, dass sie optimal in GNU R eingelesen werden können. Darüber hinaus kann mit dem Parameter type=rScript
ein R-Script zum Import der CSV-Datei abgerufen werden. Dieses Script verwendet entweder lokale Daten, wenn der Parameter csvFile
spezifiziert wurde oder holt die aktuellen Daten mittels API vom Server.
useSettings
– Die Einstellungen verwenden, die unter Daten Herunterladen festgelegt wurden (standardmäßig werden Standard-Einstellungen für die CSV-Formatierung verwendet)rScript
– Das R-Script zum Import der CSV-Daten herunterladen.csvFile
– Einen spezifischen Dateinamen im Import-Script verwenden (standardmäßig werden die Daten direkt via HTTPS vom Befragungsserver geladen)Wird ein API-Link zur Ansicht einzelner Fragebögen im Browser aufgerufen, bietet SoSci Survey ein offenes Eingabefeld für die Nummer des gewünschten Fragebogens (CASE) an. Nach Eingabe der Nummer wird die Druckansicht des Fragebogens gezeigt.
Hinweis: Wenn der API-Link nur Zugriff auf einen einzigen Fall erlaubt, wird dieser ohne Abfrage der Nummer sofort angezeigt.
Hinweis: Die Druckansicht unterliegt denselben Einschränkungen wie beim Aufruf über Erhobene Daten → Daten ansehen → Druckersymbol. Unter anderem wird in Fragen mit rotierten Items in abgeschlossenen Interviews eine andere (zufällige) Reihenfolge der Items verwendet als im Interview.
Ein API-Link zum Auflisten von Datensätzen nach Personencode muss beim Aufruf um einen Parameter SERIAL
ergänzt werden, z.B.
https://www.soscisurvey.de/project/?act=sIyhrICdaBxl6qiMagedOU1K&SERIAL=ABC12345
Zurückgegeben wird ein Objekt in JSON-Notation, welches neben dem Abfragstatus (result
) und einigen Meta-Daten (meta
) ein Array enthält, welche Datensätze mit dieser Personenkennung (SERIAL) im Datensatz vorliegen.
{ "result":"ok", "meta":{ "project":"project", "datetime":"2020-07-14 16:03:00", "count":1 }, "cases":[ { "CASE":"145", "SERIAL":"ABC12345", "FINISHED":true } ] }
Die Meta-Information count
bezieht sich auf die Anzahl passender Datensätze. Gesucht wird ausschließlich in den Datensätzen, welche die Kriterien erfüllen, die beim Anlegen des API-Links festgelegt wurden.