Datenabruf via API

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:

• Übermittlung der Daten im JSON Format
• Anzeige einzelner ausgefüllten Fragebögen (Druckansicht)
  Diese Funktion ist hilfreich, um Dritten Einsicht in ausgewählte Fragebögen zu gewähren.

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
  Einige Daten zum Datensatz, u.a. der Zeitpunkt des Datenabrufs und die Auswahlkriterien für die Datensätze (filter).
• errors
  Eventuelle Fehler beim Abruf, z.B. wenn eine nicht existierende Variable abgerufen werden sollte. Das Attribut ist nur vorhanden, wenn Fehler aufgetreten sind.
• data
  Der Datensatz, wobei die einzelnen Fälle als Attribute mit dem Schlüssel C + Nummer des Datensatzes (CASE) vorliegen.
  • C213
    Die einzelnen Fälle (Zeilen im Datensatz) sind als Objekte mit den Variablennamen als Schlüsseln und deren Ausprägung als Wert definiert. Falls für eine Variable keine Angabe vorliegt (nicht abgefragt oder keine Angabe in einer offenen Frage), wird diese nicht gelistet.

{
  "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.
  • Es können Bereiche (1-100) oder einzelne Fälle spezifiziert werden, mehrere Angaben können durch Kommata getrennt werden, z.B. 1,2,5,10-20.
  • Als letzte (!) Angabe ist auch ein offener Bereich möglich, z.B. 101-, um alle Fälle ab CASE 101 abzurufen.
  • Es kann auch eine einzelne Fall-Nummer angegeben werden.
  • Hinweis: Falls mehr Fälle angegeben werden als im API-Link erlaubt, wird der Bereich entsprechend eingeschränkt. Wenn also z.B. der API-Link den Bereich 1-100 erlaubt und der Parameter cases den Bereich 50-150 abrufen möchte, so werden die Fälle 50 bis 100 abgerufen.
• vList – Variablen, die abgerufen werden sollen.
  • Wenn der Parameter vList angegeben ist, werden nur (!) die angegeben Variablen abgerufen.
  • Die Variablen-Labels werden als Komma-separierte Liste angegeben, z.B. CASE,AB01_01,AB01_02.
  • Der Parameter 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.
  Warnung: Einige Qualitätsindikatoren werden auf Basis des heruntergeladenen Datensatzes oder Teildatensatzes normiert. Dies kann zu verzerrten oder fehlenden Werten führen, wenn nur Teildatensätze abgerufen werden.
• 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.
  • Fälle, die vor diesem Zeitpunkt begonnen wurden (STARTED), werden aus dem Download ausgeschlossen.
  • Der Zeitpunkt kann als Datum (YYYY-MM-DD) oder als Datum und Zeit (YYYY-MM-DD SS:MM:SS) angegeben werden, z.B. 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.
  • Es ist möglich, dass Interviews während des Abrufs noch nicht abgeschlossen sind. Wenn man beim nächsten Abruf der Daten den Zeitpunkt des vorigen Abrufs als changed angibt, erhält man alle seit dem letzten Abruf geänderten Fälle.

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

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 werdne 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.