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


===== Abruf der Daten als JSON =====

Standardmäßig liefert der API-Link alle erhobenen Daten (entsprechend den im API-Link festgelegten Auswahlkriterien).


==== Ausgabe ====

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

<code json>
{
  "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
    }
  }
}
</code>


==== Parameter ====

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.
  * ''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'' -- [[:de:results:variables#qualitaetsindikatoren|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 [[:de:survey:mailing#datenschutz-modus|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.
  * ''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


===== Abruf der Daten als CSV =====

CSV-Dateien (Comma Separated Values) sind kompatibel mit nahezu jedem Tabellenkalkulations- und Statistik-Programm. Es stehen dieselben [[#parameter|Parameter]] zur Verfügung wie beim JSON-Abruf.

==== CSV für Excel ====

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


==== CSV für R ====

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)


===== Anzeige einzelner Fragebögen =====

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.