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.
• variables
  Informationen zu den Variablen und Antwortcodes, die im Datensatz Verwendet werden (nur vorhanden, wenn die Parameter „infoVariables“, „infoValues“ und/oder „infoQuestionText“ angegeben wurden).

{
  "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
    }
  },  
  "variables": {
    "CASE": {
      "label": "Interview-Nummer (fortlaufend)",
      "type": "METRIC",
      "input": "SYSTEM"
    },
    "SERIAL": {
      "label": "Personenkennung oder Teilnahmecode (sofern verwendet)",
      "type": "TEXT",
      "input": "SYSTEM"
    }
  }
}

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.
  • Die Angabe des Parameters none deaktiviert den Abruf von Daten, wenn z.B. nur die Variablen und/oder Antwortcodes abgerufen werden sollen.
• SERIAL – Einschränkung auf Fälle mit dieser/n Personenkennung/en
  • Es können mehrere SERIALs durch Komma getrennt spezifiziert werden, z.B. ABCD12,BCDE23
  • Falls sowohl cases als auch SERIAL spezifiziert werden, werden nur Fälle abgerufen, welche beide Kriterien zugleich erfüllen (Schnittmenge).
• 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) 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.
• changedMin – 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 changedMin (oder changed) angibt, erhält man alle seit dem letzten Abruf geänderten Fälle.
• changedMax – Nur Fälle abrufen, die zuletzt vor diesem Zeitpunkt geändert wurden. Hinweis: Wenn keine Uhrzeit angegeben wird, wird 0:00 Uhr angenommen. Die Angabe 2022-01-01 lässt nur Fälle zu, bei denen LASTDATA vor dem 01. Januar 2022 liegt. Eine Uhrzeit kann durch Leerzeichen oder T getrennt angegeben werden, z.B. 2021-12-31T23:59:59.
• 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“.
• values – Kodierung der Antworten, erlaubt sind „codes“ (numerische Codes, Standard) und „labels“ (Texte der Auswahloptionen).

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.

Falls über den API-Link Dateien abgerufen werden sollen, kann neben der Fallnummer (case) der Parameter prefix verwendet werden, um die gewünschte Datei zu spezifizieren.

Falls kein Fall (case) angegeben wird, zeigt der API-Link eine Eingabefeld zur Eingabe der Fallnummer.

Falls für einen Fall mehrere Dateien vorliegen, werden diese zur Auswahl angeboten.

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.

Die Variablen im JSON-Download beinhalten neben einer Beschreibung („label“) die Parameter „type“ und „input“. Folgende Werte sind dafür möglich.

• type – Variablentyp/Wertebereich der Variable
  • 'BOOL' – ein boolscher Wert (true/false)
  • 'DICHOTOMOUS' – ein dichotomer Wert (1/2)
  • 'NOMINAL' – ein numerischer Wert mit nominaler Kodierung
  • 'ORDINAL' – ein numerischer Wert mit ordinaler Kodierung
  • 'METRIC' – ein numerischer Wert mit metrischer Kodierung (Ganzzahl oder Dezimalzahl)
  • 'TEXT' – ein String (Code oder Freitext mit bis zu 64k Zeichen Länge)
  • 'TIME' – eine Datums- und Zeitangabe (YYYY-MM-DD hh:mm:ss)
  • 'DATE' – eine Datumsangabe (YYYY-MM-DD)
• input – Zur Datenerhebung verwendetes Eingabeformat
  • 'OPEN' – Offenes (Text-)Eingabefeld
  • 'CHECKBOX' – Auswahlfeld ein/aus (Checkbox oder andere Visualisierung)
  • 'SELECTION' – Auswahl zwischen unterschiedlichen Optionen (Radio Button oder andere Visualisierung)
  • 'SCALE' – Auswahl zwischen ordinal geordneten Optionen
  • 'RANKING' – Einsortieren der Option gegenüber anderen Optionen
  • 'MEASURED' – Nicht-explizit durch die Befragten angegebene Daten, z.B. Reaktionszeiten
  • 'SYSTEM' – Metadaten und andere Informationen, die systemseitig erhoben/verwaltet werden
  • 'UNDEFINED' – Das Eingabeformat für die Variable ist fehlerhaft oder nicht dokumentiert.

Hinweis: Wenn der Typ einer Frage und damit der Typ einer Variable während der Erhebung geändert wird (z.B. von einem offenen Eingabefeld zu einem Skalenitem), dann können in den Daten auch andere Werte vorliegen als in der Variablenliste spezifiziert.