Exportformate und Datenstrukturen (Register nach Art. 26 Data Act)

Version: 1.0 Gültig ab: 2026-10-09 Anbieter: Paul Bengart, Keplerstraße 4A, 39104 Magdeburg, Deutschland

1 Zweck und Geltung

(1) Dieses Register beschreibt die Formate, Dateien und Datenstrukturen, in denen Choicery die Daten des Kunden zum Export bereitstellt. Es dient der Information nach Art. 26 Buchst. b der Verordnung (EU) 2023/2854 (Data Act), ergänzt die Wechsel- und Exit-Richtlinie und ist kein Vertragsbestandteil.

(2) Das Register beschreibt die aktuellen Exportformate und wird laufend aktualisiert. Dateinamen, Reihenfolge und Zahl technischer Zusatzspalten und andere Einzelheiten können sich mit der Weiterentwicklung der Anwendung ändern; maßgeblich ist der jeweilige Export.

(3) Der Kunde ruft alle in diesem Register genannten Exporte selbst über die Anwendung ab. Die Exporte stehen in allen Tarifen zur Verfügung; ausgenommen sind die Replikationspakete (Abschnitt 8.5), die nur in den Tarifen enthalten sind, die sie laut Tarifübersicht umfassen. Über die Programmierschnittstelle nach Abschnitt 11 stehen Projektliste, Projekt-Export ZIP, Rohdaten JSON und Antwortdaten im Wide-Format in allen Tarifen unentgeltlich zur Verfügung.

(4) Dateinamen in diesem Register bezeichnen Dateien innerhalb der Exporte. Wo ein Dateiname den Projektnamen, den Aufgabennamen oder eine Kennung enthält, wird dies in Worten beschrieben.

2 Übersicht der Exportwege

3 Antwortdaten im Wide-Format

3.1 Dateiformat

(1) Die CSV-Datei ist UTF-8 mit Byte Order Mark (BOM) kodiert, kommagetrennt, mit einer Kopfzeile. Werte, die Kommas, Anführungszeichen oder Zeilenumbrüche enthalten, stehen in doppelten Anführungszeichen. Der Dateiname setzt sich aus dem bereinigten Projektnamen und dem Zusatz _wide.csv zusammen; bei Export mit Nutzenwerten lautet der Zusatz _with_utilities.csv.

(2) Die Excel-Datei enthält das Blatt Data mit denselben Spalten wie die CSV-Datei und das Blatt Labels mit den Spalten Variable, Values, Label (Wertelabels aus dem Codebook).

(3) Die SPSS-Datei (.sav) enthält dieselben Spalten. Variablennamen werden auf höchstens 64 Zeichen gekürzt, beginnen mit einem Buchstaben und sind eindeutig. Variablen mit rein numerischen Codes im Codebook werden als numerische Variablen mit Wertelabels geschrieben, alle anderen als Text. Der Fragetext wird als Variablenlabel (höchstens 256 Zeichen) abgelegt. Fehlende Werte sind leere Zellen.

(4) In CSV-Dateien wird Textzellen, die mit einem formelauslösenden Zeichen beginnen (zum Beispiel Gleichheitszeichen, Plus, Minus, At-Zeichen), ein einfaches Anführungszeichen vorangestellt, damit Tabellenprogramme sie nicht als Formel ausführen. In Excel-Dateien bleibt der Wert unverändert.

(5) Der Kunde kann vor dem Export nach Antwortstatus und Teilnehmerfiltern einschränken und Spalten auswählen. Optional werden drei Metadatenspalten vorangestellt: export_timestamp_utc, export_project_id, export_project_name.

3.2 Spaltenreihenfolge

Die Spalten sind in fünf Gruppen von links nach rechts angeordnet:

1. Kennungen und Status: participant_id, unique_id, panel_id und panel_id_duplicate (nur, wenn mindestens eine Antwort eine Panel-Kennung trägt), status, experimental_condition, total_page_time, started_at, completed_at.
2. Umfragevariablen in der Reihenfolge des Umfrageablaufs. Jede Variable trägt den vom Kunden vergebenen Variablennamen; unbenannte Items erhalten einen aus dem Fragetext abgeleiteten Namen.
3. Vom Kunden im Data Editor angelegte Spalten und Spalten entfernter Items, in natürlicher Sortierung.
4. Systemmetadaten, darunter die Herkunftsspalten _choicery_design_source (Werte published, draft, legacy) und _choicery_release_id sowie panel_id_parameter (Name des URL-Parameters, über den die Panel-Kennung kam). Über personalisierte Panel-Links erfasste Panel-Kennungen werden immer ausgegeben, auch nachdem die Panel-Verknüpfung im Projekt ausgeschaltet wurde. panel_id_duplicate ist 1, wenn mehr als eine abgeschlossene Antwort dieselbe Panel-Kennung trägt, sonst 0. Geräte-, Browser-, Bildschirm-, Sprach-, Zeitzonen-, Referrer- und IP-bezogene Felder werden nicht exportiert.
5. Seitenzeiten page_time_1, page_time_2 und so weiter, ganz rechts.

3.3 Kodierungsregeln

3.4 Conjoint-Spalten

(1) Der Spaltenstamm einer Conjoint-Aufgabe besteht aus dem Typkürzel und dem Aufgabennamen, durch Unterstrich verbunden. Typkürzel sind conjoint (CBC), cbc_shop (CBC Shop), drcbc (DR-CBC), bwcbc (BW-CBC), maxdiff (MaxDiff) und anchored_maxdiff (Anchored MaxDiff).

(2) Je Choice Task folgt ein Zusatz _t1, _t2 und so weiter in der Reihenfolge der Aufgaben. Feste Aufgaben (Holdouts) tragen den Zusatz _FIXED_t1, _FIXED_t2 und so weiter entsprechend ihrer Position.

(3) Kodierung je Typ:

(4) Jede Conjoint-Aufgabe erhält zusätzlich die Spalte Stamm plus _design_version mit der Kennung der Designversion, die der Teilnehmer gesehen hat.

3.5 Status, Zeitfelder, fehlende Werte

(1) status hat die Werte complete (abgeschlossen), incomplete (nicht abgeschlossen) und manual (im Data Editor angelegte Zeile).

(2) started_at und completed_at sind Zeitstempel in UTC. Im Export über Data > Export Data werden sie als ISO 8601 mit Sekundengenauigkeit und Zeitzonenangabe +00:00 ausgegeben. In der Datei survey_responses.csv der Archive (Abschnitt 6) stehen sie im Format JJJJ-MM-TT HH:MM:SS in UTC.

(3) total_page_time und die Spalten page_time_N enthalten Sekunden mit drei Nachkommastellen.

(4) Fehlende Werte sind leere Zellen. Jede im Umfrageablauf konfigurierte Spalte ist im Export vorhanden, auch wenn kein Teilnehmer einen Wert geliefert hat.

4 Antwortdaten im Long-Format für Schätzung

(1) Das Long-Format enthält je Teilnehmer, Task und Alternative eine Zeile. Der Export erfolgt je Conjoint-Aufgabe als CSV (UTF-8 mit BOM, kommagetrennt). Der Dateiname setzt sich aus Projektname, Aufgabenname und dem Zusatz _long.csv zusammen. Attributwerte werden als Levelbezeichnungen ausgegeben.

(2) Spalten je Typ:

(3) resp.id ist die Teilnehmer-ID, dieselbe Kennung wie participant_id im Wide-Format (Abschnitt 3); Long- und Wide-Format lassen sich darüber direkt zusammenführen. ques nummeriert die Tasks fortlaufend ab 1, alt die Alternativen ab 1. choice ist 1 für die gewählte Alternative und sonst 0; bei aktivierter None-Option ist die None-Alternative die letzte Alternative eines Tasks und NoneOpt dort 1.

(4) Der Download "Preference Analysis Data (CSV)" unter Analysis > Downloads liefert dieselbe CBC-Struktur mit dem Dateinamen aus Projektkennung und _choicemodel_data.csv, kodiert als UTF-8 ohne BOM. Diese Datei ist die Eingabe der Schätzung: dort ist resp.id eine fortlaufende Teilnehmernummer ab 1; die Zuordnung zur participant_id liegt in den Respondent-Mapping-Dateien der Projektsicherung (Abschnitt 6).

5 Rohdaten JSON

(1) Der Export "Raw Responses (JSON)" ist ein JSON-Objekt, dessen Schlüssel die participant_id ist. Jeder Eintrag enthält:

Optional enthält der Export den Schlüssel _metadata mit exported_at, project_id und project_name. Der Dateiname setzt sich aus dem Projektnamen und _responses.json zusammen.

(2) Speicherschlüssel in survey_data sind die internen Item-Kennungen, nicht die Variablennamen; dadurch bleiben Daten bei Umbenennung stabil. Die Zusätze entsprechen Abschnitt 3.3 (_ao1, _i1, _i1_c1, _i1_p1, _other_text). Conjoint-Antworten liegen als Liste unter dem Schlüssel aus Typkürzel und Item-Kennung; jeder Listeneintrag beschreibt einen Task mit task_id (ab 0), bei CBC, CBC Shop und DR-CBC selected_alternative (ab 0), bei DR-CBC und BW-CBC none_response (1 oder 2), bei BW-CBC best_choice und worst_choice (ab 0), bei MaxDiff best_item und worst_item. Bei DR-CBC und BW-CBC mit getrenntem zweiten Block trägt jeder Eintrag zusätzlich block (1 oder 2). Der Schlüssel _choicery_design_context enthält Herkunft (source), Release-Kennung (release_id) und die je Aufgabe gesehene Designversion.

(3) Alternativen und Tasks sind in den Rohdaten ab 0 gezählt; die Wide-Exporte (Abschnitt 3) geben dieselben Werte ab 1 gezählt aus.

(4) Die Datei raw_responses.json innerhalb der Projektsicherung (Abschnitt 6) hat dieselbe Struktur wie der JSON-Export; die Einträge enthalten zusätzlich saved_at (Zeitpunkt der letzten Speicherung), sofern vergeben unique_id und bei Antworten mit Panel-Kennung response_metadata mit panel_id und panel_id_parameter.

6 Projekt-Export ZIP

6.1 Analysis & Re-import Archive (ZIP)

(1) Der Dateiname setzt sich aus dem Projektnamen und _project_archive.zip zusammen. Das Archiv enthält immer:

(2) Enthält das Projekt Conjoint-Aufgaben, kommen hinzu: je Aufgabe ein Ordner mit fortlaufender Nummer, Typkürzel und Aufgabenname (zum Beispiel 01_CBC_Aufgabenname); darin für CBC, CBC Shop, DR-CBC und BW-CBC die Dateien design.csv, responses.csv, labels.csv, für MaxDiff und Anchored MaxDiff data.csv und attributes.csv. Auf oberster Ebene liegen covariates.csv (Spalte sys_RespNum plus die Data-Editor-Spalten) und codebook.csv. Die Spalten dieser Dateien sind in Abschnitt 7 beschrieben.

6.2 Full Project Backup (ZIP)

(1) Der Dateiname setzt sich aus dem Projektnamen, _backup_ und einem Zeitstempel zusammen. Das Archiv enthält den vollständigen Projektordner mit Konfiguration, Designs, Antworten, Analyseläufen, Mediendateien und den veröffentlichten Versionen (Ordner _releases). Ausgeschlossen sind Sperrdateien, temporäre Dateien, automatische Sicherheitskopien, Zwischenspeicher, nicht gespeicherte Designentwürfe und die persönlichen Laufzeitdateien des Marktsimulators.

(2) Wichtige Dateien und ihre Schlüssel:

6.3 Study Definition Package

(1) Das Paket ist an eine veröffentlichte Version gebunden und enthält keine Antwortdaten. Der Dateiname setzt sich aus Projektname, _study_definition_ und der Release-Kennung zusammen. Inhalt:

7 Designdateien

7.1 CBC, CBC Shop, DR-CBC, BW-CBC

(1) Das Design liegt je Aufgabe als choice_tasks.csv vor (UTF-8 mit BOM, kommagetrennt). Spalten: participant_id (Designversion, ab 0), task_id (ab 0), alternative_id (ab 0), is_fixed_task (True für feste Aufgaben, sonst False) und je Attribut eine Spalte mit der Levelbezeichnung. Je nach Generator folgen weitere technische Spalten (fixed_task_position, obsID, profile_id, num_alts). Der Download über die Designseite trägt den Dateinamen aus choice_tasks_, Projektkennung und Designkennung.

(2) attribute_config.json enthält je Attribut die Levels in der vom Kunden definierten Reihenfolge; design_stats.json enthält Kennzahlen des Designs.

(3) Im Austauschformat der Archive (Abschnitt 6.1) hat design.csv die Spalten Version (0 = Fixed Task), Task, Concept und je Attribut eine Spalte mit dem Levelcode ab 1; Version, Task und Concept zählen ab 1, feste Aufgaben haben Version 0. responses.csv hat die Spalten sys_RespNum, Version und je Task eine Spalte aus Aufgabenname und _Fixed1, _Random1 und so weiter; DR-CBC ergänzt je Task eine Spalte mit Zusatz _none (1 = würde kaufen, 2 = würde nicht kaufen), BW-CBC verwendet je Task die Zusätze _b (beste) und _w (schlechteste Alternative) und optional _none. labels.csv hat die Spalten attribute, level, label.

7.2 MaxDiff, Anchored MaxDiff

(1) Designs liegen als JSON-Datei je Design vor. Sie enthalten name, design_type, items (Liste der Items), items_per_task, tasks_per_respondent, total_items, created_at und je nach Generator entweder tasks (ein Aufgabensatz für alle Teilnehmer) oder num_versions, respondent_designs, generator_algorithm, generator_details und balance_statistics.

(2) Antwortdaten im Austauschformat: data.csv mit ID, Set, Position, Item, Response (1 = bestes Item, -1 = schlechtestes Item, 0 = sonst); attributes.csv mit Label, Item Number; bei Anchored MaxDiff calibration.csv mit ID, Item, Anchor (1 = ja, 0 = nein). Der Download "MaxDiff Responses (Long Format)" unter Analysis > Downloads liefert dieselben Dateien als ZIP mit Dateinamen aus Aufgabenname und Designkennung.

8 HB-Ergebnisse

8.1 hb_results.json (CBC, CBC Shop, DR-CBC, BW-CBC, TasteNet)

(1) Jeder HB-Lauf speichert hb_results.json in einem einheitlichen Schema (schema_version 1). Pflichtfelder:

Weitere Felder sind unter anderem estimation_date, zc_column_names, zc_betas_individual, zc_mean, importance_individual, attribute_importance, summary_utilities, rlh_individual, flagged_respondents, none_option_enabled, none_opt_utility, iterations, burn_in, n_chains, config, warnings, task_id, task_type.

(2) Parameternamen in beta_individual folgen einer festen Konvention: kategoriales Level Attribut_Level (zum Beispiel Farbe_Schwarz), lineares Attribut nur der Attributname (zum Beispiel Preis), None-Option NoneOpt oder ASC_none.

(3) MaxDiff und Anchored MaxDiff speichern ein eigenes Schema mit analysis_type (maxdiff oder anchored_maxdiff), item_labels, n_items, n_respondents, engine, schema_version und je Skala ein Objekt Itemlabel zu Liste der individuellen Werte.

8.2 CSV-Ergebnisdateien je Lauf

(1) CBC-Familie (UTF-8 mit BOM): Individual_Utilities_Raw.csv und Individual_Utilities_ZC_Diffs.csv (Spalten Respondent, RLH, bei Konvergenzdiagnostik Rhat_Max und Rhat_Mean, dann je Parameter eine Spalte), Individual_Importances.csv (Respondent und je Attribut eine Spalte), Summary_Utilities.csv, Diagnostics.csv, Flagged_Respondents.csv, Config.csv, Attribute_Labels.csv; je nach Einstellung Respondent_Holdout_Predictions.csv, Parameter_Diagnostics.csv sowie bei Kovariaten Covariate_Alpha_Draws.csv, Covariate_Effects_Columns.csv, Covariate_Effects_Summary.csv, Covariate_Effects_ZC_Diffs_Summary.csv, Covariate_Importances_Summary.csv, Covariate_Explained_Share_Summary.csv.

(2) MaxDiff-Familie: Probability_Scale.csv, Softmax_Preference_Share.csv, Zero_Anchored_Interval_Scale.csv, Zero_Centered_Raw_Scores.csv, Summary.csv, Diagnostics.csv, Parameter_Diagnostics.csv, Flagged_Respondents.csv, Settings.csv.

(3) Unter Analysis > Downloads sind Parameter_Diagnostics.csv und Diagnostics.csv einzeln abrufbar; die Advanced-Verfahren liefern alle CSV-Dateien eines Laufs als ZIP.

8.3 Excel-Berichte

(1) CBC-Familie: Dateiname aus Aufgabenname, Designkennung und _HB_Results.xlsx; Blätter Summary, Settings & Diagnostics, Raw Part-Worths, ZC-Diffs Part-Worths, Importances.

(2) MaxDiff-Familie: maxdiff_hb_results.xlsx im Laufordner, Download als MaxDiff_HB_Results.xlsx mit Designkennung; Blätter Summary, Settings Summary, Probability Scale, Preference Index, Worst-Zero Interval Scale, Zero-Centered Raw Scores, Parameter Diagnostics; bei Anchored MaxDiff zusätzlich Anchor Summary, Purchase Probability, Anchored Utilities, Consideration Sets.

8.4 Nutzenwerte im Wide-Export

Beim Export mit Nutzenwerten (Abschnitt 2, Preference Scores) werden je gewähltem Lauf Spalten an die Wide-Tabelle angehängt. Der Spaltenname beginnt mit dem bereinigten Laufnamen (ohne Laufname die Laufkennung), gefolgt von _raw_utilities_ plus Parametername, _ZC_utilities_ plus Parametername oder _importance_ plus Attributname; die None-Option erhält den Zusatz _none_option.

8.5 Replikationspakete

(1) Das Julia-Replikationspaket für HB heißt nach Projektname, _Julia_HB_Package_ und Laufname. Inhalt des Paketordners:

Das Skript schreibt seine Ergebnisse in den Ordner results und erzeugt eine Datei mit Endung _IMPORT_INTO_CHOICERY.zip, die in Choicery importiert werden kann; Population_Covariance_Draws.csv verbleibt nur lokal.

(2) Die Replikationspakete für Latent Class, Interaction Search und TasteNet sind Python-Pakete mit README.md, MANIFEST.json, requirements.txt, dem Ausführungsskript, dem Ordner data mit Eingabedaten, dem Ordner _docs mit Parameter- und Ausgabebeschreibung sowie demselben Ordner _legal.

9 Weitere Exporte

(1) Excel-Berichte: Der Wide-Export als Excel enthält die Blätter Data und Labels (Abschnitt 3.1); die HB-Berichte sind in Abschnitt 8.3 beschrieben.

(2) SPSS: Die Datei .sav (Abschnitt 3.1) trägt den Projektnamen, bei Nutzenwerten mit Zusatz _with_utilities.

(3) Codebook: codebook.xlsx (Dateiname aus Projektname und _codebook.xlsx) enthält das Blatt Codebook mit den Spalten Variable, Page, Question / Description, Type, Value range, Coding / Response options sowie die Blätter Study Metadata, Item Configuration und Choice Designs.

(4) Marktsimulator: Der Excel-Export einer Simulation enthält die Blätter Summary, Individual Choices, Individual Probabilities und Product Definitions; der Export einer Zahlungsbereitschaftsanalyse die Blätter Summary, Segment WTP, Segment Coding und Methodology; der Export einer Share-of-Preference-Iteration die Blätter Summary, Scenarios und Focal Profile. Ergebnisse von Share-of-Preference-Iterationen sind außerdem als CSV abrufbar, Berechnungsprotokolle (etwa zu Simulation und Zahlungsbereitschaft) als Textdatei (TXT) und Simulationsberichte als PDF.

(5) Aktivitätsprotokoll: Als CSV mit den Spalten Timestamp (mit Angabe der Zeitzone), User, Action, Item, Item Type, Details oder als Textdatei mit den Spalten Timestamp, User, Action, Item, Details in fester Breite.

(6) Latent Class, TasteNet und Interaction Search (Advanced Analytics) liefern je Lauf einen Excel-Bericht, alle CSV-Dateien als ZIP, die Ergebnisse als JSON und ein Replikationspaket (Abschnitt 8.5, tarifgebunden).

(7) PDF-Berichte: Für HB, Latent Class, TasteNet und Interaction Search sowie für den Marktsimulator lässt sich die Ergebnisansicht als PDF-Bericht herunterladen. Die Berichte dienen der Darstellung; die Ergebnisse selbst stehen strukturiert in den Excel-, CSV- und JSON-Exporten.

(8) Weitere Downloads (Ergebnistabellen der Umfrageauswertung als CSV, XLSX, DOCX oder RTF, Studiendokumentation und Papierfassung der Umfrage als PDF oder DOCX) sind aus den Daten der strukturierten Exporte dieses Registers abgeleitete Darstellungen und haben keine feste Datenstruktur.

10 Kontoexport

(1) Unter Profile > Personal data lädt der Kunde die Datei choicery-personal-data.zip. Sie enthält ausschließlich kontobezogene Daten; Projektinhalte, Antworten, Designs und Analyseergebnisse werden über die Projektexporte (Abschnitte 3 bis 9) bereitgestellt.

(2) Inhalt:

(3) Zeitstempel sind ISO 8601; Wahrheitswerte sind true oder false; Listen sind mit Semikolon getrennt.

11 Programmierschnittstelle für den Wechsel (Art. 30 Abs. 2 Data Act)

(1) Zweck. Die Schnittstelle stellt die für einen Wechsel zu einem anderen Anbieter oder in eine eigene Umgebung erforderlichen Daten zum automatisierten Abruf bereit. Sie ist nur lesend und steht in allen Tarifen unentgeltlich zur Verfügung. Die Zugriffsrechte auf Projekte sind dieselben wie in der Benutzeroberfläche.

(2) Authentifizierung. Jeder Aufruf trägt einen persönlichen Zugriffstoken im HTTP-Header Authorization: Bearer <Token>. Tokens verwaltet der Kunde unter Profile > API access: Er vergibt einen Namen, erhält den Token einmalig angezeigt und kann ihn jederzeit widerrufen. Je Konto sind derzeit höchstens fünf aktive Tokens möglich. Ein Token beginnt mit chc_; der Anbieter speichert nur seinen SHA-256-Hash sowie die ersten zwölf Zeichen zur Anzeige. Sitzungen und Cookies der Benutzeroberfläche wertet die Schnittstelle nicht aus.

(3) Endpunkte. Basis ist https://app.choicery.ai/api/v1; <project_id> ist die Kennung aus der Projektliste. Alle Endpunkte werden mit HTTP GET aufgerufen.

Dateiantworten tragen Content-Disposition: attachment. Antwortdateien und Projektsicherungen verwenden den Namen des jeweiligen UI-Downloads; das API-Codebuch heißt <Projektname>_codebook.csv, die Wertbeschriftungen <Projektname>_value_labels.csv, jeweils mit bereinigtem Projektnamen. Die Variablennamen sind die der Antwortspalten, auch bei Fragen ohne eigenen Namen (aus dem Fragetext abgeleiteter Name) und bei kollidierenden Namen (Zusatz). Zusätzliche Data-Editor-Spalten haben keine Codebuchbeschreibung. Wertbeschriftungen über variable und code verbinden und nicht zugeordnete Antworten erhalten.

Parameter für responses.csv und responses.json (jeweils höchstens einmal, nie leer; ein ungültiger Wert ergibt 400):

Zeitfenster: Ein Tag meint den Kalendertag in Europe/Berlin; since beginnt um 0 Uhr, until schließt den genannten Tag ein. Ein Zeitpunkt ohne Zeitzone wird abgelehnt; ein + im Zeitversatz ist in der URL als %2B zu schreiben. Grenzen aus Zeitpunkten sind halboffen, aufeinanderfolgende Fenster enthalten eine Antwort also genau einmal. Antworten ohne verwertbaren Zeitpunkt fallen bei gesetztem Zeitfenster heraus. Ein Fenster ohne Treffer liefert eine CSV-Datei nur mit Kopfzeile bzw. ein leeres JSON-Objekt. Eine nicht abgeschlossene Antwort wechselt beim Abschluss vom Start- zum Abschlusszeitpunkt; für schrittweise Abrufe empfiehlt sich daher status=complete. Spätere Änderungen im Data Editor und Löschungen älterer Antworten erfasst ein Zeitfenster nicht; einen vollständigen Stand liefert ein Abruf ohne Zeitfenster.

Antworttexte (labels=text): Spalten von Einfachauswahl, Likert-Skala und Produktbewertung mit Einfachauswahl werden nur umgewandelt, wenn jeder Code des Wertebereichs eindeutig beschriftet ist. Rankings, teilbeschriftete Skalen, Semantische Differentiale, Mehrfachauswahl (0/1), Zahlen, Freitexte, Conjoint- und Systemspalten behalten ihre Werte. Kann eine nicht leere Antwort nicht zugeordnet werden, etwa eine gelöschte Option, bleibt für diesen Download die gesamte Spalte unverändert. Importierte Codes wie 01, Dezimalcodes und Textkennungen werden nicht umgewandelt. Fehlende Werte bleiben fehlend. Eine Andere-Auswahl kann zu Other werden; ihr separates Freitextfeld behält die Eingabe. Der CSV-Formelschutz gilt auch für eingesetzte Labels und Fragetexte im Codebuch. Für Berechnungen und Sortierung Codes zusammen mit dem Codebuch verwenden. Es beschreibt die aktuelle Konfiguration, keine historischen Antwortdefinitionen.

(4) Beispielaufrufe mit curl (Token einsetzen):

curl -H "Authorization: Bearer chc_..." https://app.choicery.ai/api/v1/projects

curl -H "Authorization: Bearer chc_..." -o projekt.zip https://app.choicery.ai/api/v1/projects/<project_id>/export.zip

curl -H "Authorization: Bearer chc_..." -o antworten.csv https://app.choicery.ai/api/v1/projects/<project_id>/responses.csv

curl -H "Authorization: Bearer chc_..." -o neu.csv "https://app.choicery.ai/api/v1/projects/<project_id>/responses.csv?labels=text&status=complete&since=2026-10-15T08:00:00Z"

Für Power BI und Excel (Power Query) zeigt Data > Export im Tarif Pro unter "Load in Power BI or Excel" die Projektadressen und eine fertige Abfrage. Diese im erweiterten Editor von Power Query einfügen, nur <YOUR_TOKEN> dort ersetzen, das Präfix Bearer erhalten und als Anmeldung "Anonym" wählen. Die Choicery-Export-Seite zeigt den Token nie an und nimmt ihn nicht entgegen. Eine URL allein überträgt nicht den erforderlichen Authorization-Header.

Für Google Sheets bietet Data > Export im Tarif Pro eine eigene Verbindung an, die ohne Zugriffstoken der Schnittstelle auskommt. Nach der Anmeldung bei Google mit einem Google-Konto der eigenen Wahl und der Bestätigung des angezeigten Kontos legt Choicery in dessen Google Drive eine neue Tabelle an und aktualisiert sie etwa jede Stunde. Zwei Varianten stehen zur Wahl: Antworttexte im Blatt "Answers" oder Codes im Blatt "Answers" zusammen mit dem Codebuch im Blatt "Codebook" (derselbe Inhalt wie das API-codebook.csv: eine Zeile je Spalte von "Answers"). Der Inhalt entspricht dem Antwortexport im Breitformat (Abschnitt 3) mit allen Antworten einschließlich unvollständiger. Die Blätter "Answers" und "Codebook" gehören Choicery und werden bei jeder Aktualisierung vollständig ersetzt; eigene Auswertungen gehören in andere Blätter, die unverändert bleiben. Sehr große Exporte lehnt Choicery mit einem Hinweis auf Power BI oder Excel ab, statt sie abzuschneiden: Eine Aktualisierung darf derzeit höchstens 10 MB in einer Schreibanfrage übertragen, und die Tabelle darf höchstens 10 Millionen Zellen haben. Choicery löscht die Tabelle nicht; nach "Stop updating" oder dem Trennen im Profil bleibt sie im Google Drive.

Für die inkrementelle Aktualisierung in Power BI die Parameter RangeStart und RangeEnd vom Typ Datum/Uhrzeit anlegen, ihre Werte ausdrücklich als UTC behandeln und den Query-Eintrag der Vorlage ersetzen:

Query = [
    labels = "codes",
    status = "complete",
    since = DateTime.ToText(RangeStart, [Format="yyyy-MM-dd'T'HH:mm:ss.ffffff'Z'", Culture="en-US"]),
    until = DateTime.ToText(RangeEnd, [Format="yyyy-MM-dd'T'HH:mm:ss.ffffff'Z'", Culture="en-US"])
]

Feste Basis-URL, RelativePath und Authorization-Header erhalten. Die Aktualisierungsrichtlinie getrennt einrichten und die Abfrage in Desktop und Power BI Service prüfen. Zeitpunkte statt inklusiver Endtage verwenden. Ein vollständiger Neuabgleich braucht einen Abruf ohne Status- und Zeitfilter sowie das Ersetzen des bisherigen lokalen Datenstands einschließlich gelöschter Zeilen. Diese Endpunkte liefern kein Änderungsprotokoll.

(5) Begrenzungen. Je Token und Endpunkt sind derzeit 60 Aufrufe pro Minute zulässig. Die Antwort-Header X-RateLimit-Limit und X-RateLimit-Remaining sowie bei Überschreitung Retry-After geben den Stand an. Vor erneutem Abruf nach 429 die Wartezeit aus Retry-After beachten. Antworten tragen Cache-Control: no-store, Pragma: no-cache und Referrer-Policy: no-referrer. Nach erfolgreicher Token-Authentifizierung wird api_token.used mit Endpunkt und Ergebnis im Kontoprotokoll vermerkt (Abschnitt 10, Datei account_activity.csv). Eine Projektkennung wird erst nach erfolgreicher Zugriffsprüfung angehängt. Ablehnungen vor der Token-Authentifizierung, auch ein früh greifendes Rate-Limit, erzeugen dieses Ereignis nicht.

(6) Fehler. Fehlerantworten sind JSON-Objekte mit dem Feld error (Text) und, sofern zutreffend, error_code:

12 Standards und Interoperabilität

Zeichensatz aller Textexporte ist UTF-8. Zeitstempel der Antwortdaten sind UTC; das Aktivitätsprotokoll nennt die verwendete Zeitzone in der Kopfzeile. Die participant_id ist in allen Antwortexporten dieselbe Kennung; im Long-Format über Data > Export Data steht sie in resp.id (Abschnitt 4 Abs. 3). In den Eingabedaten der Schätzung (Abschnitt 4 Abs. 4) und in den HB-Ergebnissen (Abschnitt 8, Spalte Respondent) ist die Teilnehmerkennung dagegen eine fortlaufende Nummer des jeweiligen Laufs; die Zuordnung zur participant_id enthalten die Mapping-Dateien der Projektsicherung (Abschnitt 6.2). Über diese Kennungen lassen sich Wide-Format, Long-Format, Rohdaten und HB-Ergebnisse zusammenführen.