Export Formats and Data Structures (Register under Article 26 Data Act)

Version: 1.0 Effective from: 2026-10-09 Provider: Paul Bengart, Keplerstraße 4A, 39104 Magdeburg, Germany

1 Purpose and Scope

(1) This register describes the formats, files and data structures in which Choicery makes the Customer's data available for export. It serves as information under Article 26(b) of Regulation (EU) 2023/2854 (Data Act), supplements the Data Act Exit and Switching Policy and does not form part of the contract.

(2) The register describes the current export formats and is updated on an ongoing basis. File names, the order and number of technical additional columns and other details may change as the application is developed further; the respective export is authoritative.

(3) The Customer retrieves every export named in this register directly through the application. The exports are available in all plans; excepted are the replication packages (Section 8.5), which are included only in the plans that include them according to the plan overview. Through the programming interface under Section 11, the project list, the project export ZIP, the raw JSON and the wide-format response data are available in all plans free of charge.

(4) File names in this register denote files inside the exports. Where a file name contains the project name, the task name or an identifier, this is described in words.

2 Overview of Export Paths

3 Response Data in Wide Format

3.1 File format

(1) The CSV file is encoded as UTF-8 with a byte order mark (BOM), comma-separated, with one header row. Values containing commas, quotation marks or line breaks are enclosed in double quotation marks. The file name consists of the sanitised project name and the suffix _wide.csv; for an export with utilities the suffix is _with_utilities.csv.

(2) The Excel file contains the sheet Data with the same columns as the CSV file and the sheet Labels with the columns Variable, Values, Label (value labels from the codebook).

(3) The SPSS file (.sav) contains the same columns. Variable names are shortened to at most 64 characters, start with a letter and are unique. Variables whose codebook codes are purely numeric are written as numeric variables with value labels; all others as strings. The question text is stored as the variable label (at most 256 characters). Missing values are empty cells.

(4) In CSV files, text cells that begin with a formula-triggering character (for example equals sign, plus, minus, at sign) are prefixed with a single quotation mark so that spreadsheet programs do not execute them as formulas. In Excel files the value remains unchanged.

(5) Before exporting, the Customer can restrict the data by response status and participant filters and select columns. Optionally three metadata columns are prepended: export_timestamp_utc, export_project_id, export_project_name.

3.2 Column order

The columns are arranged from left to right in five groups:

1. Identifiers and status: participant_id, unique_id, panel_id and panel_id_duplicate (only when at least one response carries a panel ID), status, experimental_condition, total_page_time, started_at, completed_at.
2. Survey variables in survey flow order. Each variable carries the variable name assigned by the Customer; unnamed items receive a name derived from the question text.
3. Columns created by the Customer in the Data Editor and columns of removed items, in natural sort order.
4. System metadata, including the provenance columns _choicery_design_source (values published, draft, legacy) and _choicery_release_id, and panel_id_parameter (name of the URL parameter the panel ID came in). Panel IDs collected through personalized panel links are always output, also after panel linkage has been switched off in the project. panel_id_duplicate is 1 when more than one completed response carries the same panel ID, otherwise 0. Device, browser, screen, language, time zone, referrer and IP-related fields are not exported.
5. Page times page_time_1, page_time_2 and so on, at the far right.

3.3 Coding rules

3.4 Conjoint columns

(1) The column stem of a conjoint task consists of the type key and the task name, joined by an underscore. Type keys are conjoint (CBC), cbc_shop (CBC Shop), drcbc (DR-CBC), bwcbc (BW-CBC), maxdiff (MaxDiff) and anchored_maxdiff (Anchored MaxDiff).

(2) Each choice task is followed by a suffix _t1, _t2 and so on in task order. Fixed tasks (holdouts) carry the suffix _FIXED_t1, _FIXED_t2 and so on according to their position.

(3) Coding per type:

(4) Each conjoint task additionally receives the column stem plus _design_version with the identifier of the design version the respondent saw.

3.5 Status, time fields, missing values

(1) status has the values complete, incomplete and manual (row created in the Data Editor).

(2) started_at and completed_at are timestamps in UTC. In the export via Data > Export Data they are written as ISO 8601 with second precision and the time zone designator +00:00. In the file survey_responses.csv of the archives (Section 6) they are written in the format YYYY-MM-DD HH:MM:SS in UTC.

(3) total_page_time and the columns page_time_N contain seconds with three decimal places.

(4) Missing values are empty cells. Every column configured in the survey flow is present in the export even if no respondent supplied a value.

4 Response Data in Long Format for Estimation

(1) The long format contains one row per respondent, task and alternative. The export is generated per conjoint task as CSV (UTF-8 with BOM, comma-separated). The file name consists of the project name, the task name and the suffix _long.csv. Attribute values are written as level labels.

(2) Columns per type:

(3) resp.id is the participant ID, the same identifier as participant_id in the wide format (Section 3); long and wide format can be joined directly on it. ques numbers the tasks consecutively from 1, alt the alternatives from 1. choice is 1 for the chosen alternative and otherwise 0; when the none option is enabled, the none alternative is the last alternative of a task and NoneOpt is 1 there.

(4) The download "Preference Analysis Data (CSV)" under Analysis > Downloads delivers the same CBC structure with a file name made of the project identifier and _choicemodel_data.csv, encoded as UTF-8 without BOM. This file is the input of the estimation: there resp.id is a consecutive respondent number starting at 1; the mapping to participant_id is held in the respondent mapping files of the project backup (Section 6).

5 Raw Data JSON

(1) The export "Raw Responses (JSON)" is a JSON object whose keys are the participant_id. Each entry contains:

Optionally the export contains the key _metadata with exported_at, project_id and project_name. The file name consists of the project name and _responses.json.

(2) Storage keys in survey_data are the internal item identifiers, not the variable names; this keeps data stable when items are renamed. The suffixes correspond to Section 3.3 (_ao1, _i1, _i1_c1, _i1_p1, _other_text). Conjoint answers are stored as a list under the key made of type key and item identifier; each list entry describes one task with task_id (from 0), for CBC, CBC Shop and DR-CBC selected_alternative (from 0), for DR-CBC and BW-CBC none_response (1 or 2), for BW-CBC best_choice and worst_choice (from 0), for MaxDiff best_item and worst_item. For DR-CBC and BW-CBC with a separate second block each entry additionally carries block (1 or 2). The key _choicery_design_context contains the provenance (source), the release identifier (release_id) and the design version seen per task.

(3) Alternatives and tasks are counted from 0 in the raw data; the wide exports (Section 3) write the same values counted from 1.

(4) The file raw_responses.json inside the project backup (Section 6) has the same structure as the JSON export; the entries additionally contain saved_at (time of the last save), where assigned unique_id, and for responses with a panel ID response_metadata with panel_id and panel_id_parameter.

6 Project Export ZIP

6.1 Analysis & Re-import Archive (ZIP)

(1) The file name consists of the project name and _project_archive.zip. The archive always contains:

(2) If the project contains conjoint tasks, the following are added: one folder per task with a running number, type key and task name (for example 01_CBC_Taskname); inside it, for CBC, CBC Shop, DR-CBC and BW-CBC the files design.csv, responses.csv, labels.csv, for MaxDiff and Anchored MaxDiff data.csv and attributes.csv. At the top level are covariates.csv (column sys_RespNum plus the Data Editor columns) and codebook.csv. The columns of these files are described in Section 7.

6.2 Full Project Backup (ZIP)

(1) The file name consists of the project name, _backup_ and a timestamp. The archive contains the complete project folder with configuration, designs, responses, analysis runs, media files and the published versions (folder _releases). Excluded are lock files, temporary files, automatic safety copies, caches, unsaved design drafts and the personal runtime files of the market simulator.

(2) Important files and their keys:

6.3 Study Definition Package

(1) The package is bound to a published version and contains no response data. The file name consists of the project name, _study_definition_ and the release identifier. Contents:

7 Design Files

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

(1) The design is stored per task as choice_tasks.csv (UTF-8 with BOM, comma-separated). Columns: participant_id (design version, from 0), task_id (from 0), alternative_id (from 0), is_fixed_task (True for fixed tasks, otherwise False) and one column per attribute with the level label. Depending on the generator, further technical columns follow (fixed_task_position, obsID, profile_id, num_alts). The download from the design page carries a file name made of choice_tasks_, the project identifier and the design identifier.

(2) attribute_config.json contains the levels of each attribute in the order defined by the Customer; design_stats.json contains the design statistics.

(3) In the exchange format of the archives (Section 6.1), design.csv has the columns Version (0 = Fixed Task), Task, Concept and one column per attribute with the level code from 1; Version, Task and Concept count from 1, fixed tasks have Version 0. responses.csv has the columns sys_RespNum, Version and one column per task made of the task name and _Fixed1, _Random1 and so on; DR-CBC adds one column per task with suffix _none (1 = would buy, 2 = would not buy), BW-CBC uses per task the suffixes _b (best) and _w (worst alternative) and optionally _none. labels.csv has the columns attribute, level, label.

7.2 MaxDiff, Anchored MaxDiff

(1) Designs are stored as one JSON file per design. They contain name, design_type, items (list of items), items_per_task, tasks_per_respondent, total_items, created_at and, depending on the generator, either tasks (one task set for all respondents) or num_versions, respondent_designs, generator_algorithm, generator_details and balance_statistics.

(2) Response data in the exchange format: data.csv with ID, Set, Position, Item, Response (1 = best item, -1 = worst item, 0 = otherwise); attributes.csv with Label, Item Number; for Anchored MaxDiff calibration.csv with ID, Item, Anchor (1 = yes, 0 = no). The download "MaxDiff Responses (Long Format)" under Analysis > Downloads delivers the same files as a ZIP with file names made of the task name and the design identifier.

8 HB Results

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

(1) Every HB run stores hb_results.json in a uniform schema (schema_version 1). Required fields:

Further fields include 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) Parameter names in beta_individual follow a fixed convention: categorical level Attribute_Level (for example Color_Black), linear attribute the attribute name only (for example Price), none option NoneOpt or ASC_none.

(3) MaxDiff and Anchored MaxDiff store their own schema with analysis_type (maxdiff or anchored_maxdiff), item_labels, n_items, n_respondents, engine, schema_version and, per scale, an object mapping item label to the list of individual values.

8.2 CSV result files per run

(1) CBC family (UTF-8 with BOM): Individual_Utilities_Raw.csv and Individual_Utilities_ZC_Diffs.csv (columns Respondent, RLH, with convergence diagnostics Rhat_Max and Rhat_Mean, then one column per parameter), Individual_Importances.csv (Respondent and one column per attribute), Summary_Utilities.csv, Diagnostics.csv, Flagged_Respondents.csv, Config.csv, Attribute_Labels.csv; depending on settings Respondent_Holdout_Predictions.csv, Parameter_Diagnostics.csv and, with covariates, 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 family: 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) Under Analysis > Downloads, Parameter_Diagnostics.csv and Diagnostics.csv can be downloaded individually; the Advanced Analytics methods deliver all CSV files of a run as a ZIP.

8.3 Excel reports

(1) CBC family: file name made of the task name, the design identifier and _HB_Results.xlsx; sheets Summary, Settings & Diagnostics, Raw Part-Worths, ZC-Diffs Part-Worths, Importances.

(2) MaxDiff family: maxdiff_hb_results.xlsx in the run folder, downloaded as MaxDiff_HB_Results.xlsx with the design identifier; sheets Summary, Settings Summary, Probability Scale, Preference Index, Worst-Zero Interval Scale, Zero-Centered Raw Scores, Parameter Diagnostics; for Anchored MaxDiff additionally Anchor Summary, Purchase Probability, Anchored Utilities, Consideration Sets.

8.4 Utilities in the wide export

For an export with utilities (Section 2, Preference Scores), columns are appended to the wide table for each selected run. The column name starts with the sanitised run name (or the run identifier when no run name exists), followed by _raw_utilities_ plus parameter name, _ZC_utilities_ plus parameter name or _importance_ plus attribute name; the none option receives the suffix _none_option.

8.5 Replication packages

(1) The Julia replication package for HB is named after the project name, _Julia_HB_Package_ and the run name. Contents of the package folder:

The script writes its results to the folder results and produces a file ending in _IMPORT_INTO_CHOICERY.zip that can be imported into Choicery; Population_Covariance_Draws.csv remains local only.

(2) The replication packages for Latent Class, Interaction Search and TasteNet are Python packages with README.md, MANIFEST.json, requirements.txt, the runner script, the folder data with input data, the folder _docs with parameter and output descriptions and the same folder _legal.

9 Further Exports

(1) Excel reports: the wide export as Excel contains the sheets Data and Labels (Section 3.1); the HB reports are described in Section 8.3.

(2) SPSS: the .sav file (Section 3.1) carries the project name, with the suffix _with_utilities when utilities are included.

(3) Codebook: codebook.xlsx (file name made of the project name and _codebook.xlsx) contains the sheet Codebook with the columns Variable, Page, Question / Description, Type, Value range, Coding / Response options and the sheets Study Metadata, Item Configuration and Choice Designs.

(4) Market simulator: the Excel export of a simulation contains the sheets Summary, Individual Choices, Individual Probabilities and Product Definitions; the export of a willingness-to-pay analysis the sheets Summary, Segment WTP, Segment Coding and Methodology; the export of a share-of-preference iteration the sheets Summary, Scenarios and Focal Profile. Results of share-of-preference iterations are also available as CSV, calculation logs (for example for the simulation and willingness to pay) as text files (TXT) and simulation reports as PDF.

(5) Activity log: as CSV with the columns Timestamp (with the time zone stated), User, Action, Item, Item Type, Details, or as a text file with the columns Timestamp, User, Action, Item, Details in fixed width.

(6) Latent Class, TasteNet and Interaction Search (Advanced Analytics) deliver per run an Excel report, all CSV files as a ZIP, the results as JSON and a replication package (Section 8.5, plan-bound).

(7) PDF reports: for HB, Latent Class, TasteNet and Interaction Search as well as for the market simulator, the results view can be downloaded as a PDF report. The reports serve presentation purposes; the results themselves are available in structured form in the Excel, CSV and JSON exports.

(8) Further downloads (result tables of the survey analysis as CSV, XLSX, DOCX or RTF, study documentation and paper version of the survey as PDF or DOCX) are presentations derived from the data in the structured exports of this register and have no fixed data structure.

10 Account Export

(1) Under Profile > Personal data the Customer downloads the file choicery-personal-data.zip. It contains account-level data only; project content, responses, designs and analysis results are provided through the project exports (Sections 3 to 9).

(2) Contents:

(3) Timestamps are ISO 8601; boolean values are true or false; lists are separated by semicolons.

11 Programming Interface for Switching (Article 30(2) Data Act)

(1) Purpose. The interface makes the data required for switching to another provider or to the Customer's own environment available for automated retrieval. It is read-only and is available in all plans free of charge. Project access rights are the same as in the user interface.

(2) Authentication. Every call carries a personal access token in the HTTP header Authorization: Bearer <token>. The Customer manages tokens under Profile > API access: they assign a name, see the token once and can revoke it at any time. At present, at most five active tokens per account are possible. A token starts with chc_; the Provider stores only its SHA-256 hash and the first twelve characters for display. The interface does not evaluate sessions or cookies of the user interface.

(3) Endpoints. The base is https://app.choicery.ai/api/v1; <project_id> is the identifier from the project list. All endpoints are called with HTTP GET.

File responses carry Content-Disposition: attachment. Response files and project backups use the respective UI download name; the API codebook uses <project_name>_codebook.csv and the value labels <project_name>_value_labels.csv, each with a sanitized project name. Variable names are those of the response columns, also for questions without a name of their own (name derived from the question text) and for conflicting names (suffix). Added Data Editor columns have no codebook description. Join the value labels on both variable and code, retaining unmatched answers.

Parameters of responses.csv and responses.json (each at most once, never empty; an invalid value returns 400):

Time windows: a day means the calendar day in Europe/Berlin; since starts at midnight, until includes the named day. A timestamp without a time zone is rejected; a + in the offset must be written as %2B in the URL. Bounds given as timestamps are half-open, so consecutive windows contain a response exactly once. Responses without a usable time are left out when a time window is set. A window without matches returns a CSV file with the header row only or an empty JSON object. A response not completed moves from its start time to its completion time when it is completed; for incremental retrieval status=complete is therefore recommended. A time window does not capture later changes in the Data Editor or deletions of older responses; a retrieval without a time window returns the complete state.

Answer texts (labels=text): columns of single choice, Likert scale and single-choice product evaluation are converted only when every code of the value range has an unambiguous label. Rankings, partly labelled scales, semantic differentials, multiple choice (0/1), numbers, free text, conjoint and system columns keep their stored values. If a nonblank answer cannot be mapped, for example a deleted option, the entire column stays unchanged for that download. Imported codes such as 01, fractional codes and text identifiers are not converted. Missing cells remain missing. Other selections can become Other; their separate free-text fields retain their input. CSV formula protection also applies to the inserted labels and codebook question text. For calculations and sorting, use codes together with the codebook. It describes the current configuration, not historical option definitions.

(4) Example calls with curl (insert token):

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

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

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

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

For Power BI and Excel (Power Query), Data > Export on Pro plans shows the project's addresses and a ready-made query under "Load in Power BI or Excel". Paste it into the Advanced Editor in Power Query, replace only <YOUR_TOKEN> there, retain the Bearer prefix and choose "Anonymous" as sign-in. The Choicery export page never displays or accepts the token. A URL alone does not supply the required Authorization header.

For Google Sheets, Data > Export on Pro plans offers a connection of its own that needs no access token of the interface. After signing in to Google with a Google account of one's choice and confirming the account shown, Choicery creates a new spreadsheet in that account's Google Drive and updates it about every hour. Two variants are available: answer texts in the sheet "Answers", or codes in the sheet "Answers" together with the codebook in the sheet "Codebook" (the same content as the API codebook.csv: one row per column of "Answers"). The content is the same as the wide response export (Section 3), with all responses including incomplete ones. The sheets "Answers" and "Codebook" belong to Choicery and are replaced completely on each update; own analyses belong in other sheets, which remain unchanged. Choicery refuses very large exports with a hint to Power BI or Excel instead of truncating them: at present, an update may transfer at most 10 MB in one write request, and the spreadsheet may have at most 10 million cells. Choicery does not delete the spreadsheet; after "Stop updating" or disconnecting in the profile, it stays in the Google Drive.

For Power BI incremental refresh, create the date/time parameters RangeStart and RangeEnd, explicitly interpret them as UTC, and replace the template's Query record with:

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"])
]

Keep the fixed base URL, RelativePath and Authorization header. Configure the refresh policy separately and verify the query in Desktop and the Power BI Service. Use timestamp bounds, not inclusive end-day values. A full reconciliation requires a request without status or time filters and replacement of the previous local data, including deleted rows. These endpoints are not a change feed.

(5) Limits. At present, 60 calls per minute are permitted per token and endpoint. The response headers X-RateLimit-Limit and X-RateLimit-Remaining, and Retry-After when the limit is exceeded, report the current state. Wait for Retry-After before retrying a 429 response. Responses carry Cache-Control: no-store, Pragma: no-cache and Referrer-Policy: no-referrer. Requests that reach successful token authentication emit api_token.used with endpoint and outcome in the account log (Section 10, file account_activity.csv). A project identifier is attached only after successful access validation. Rejections before token authentication, including an early rate limit, do not emit this event.

(6) Errors. Error responses are JSON objects with the field error (text) and, where applicable, error_code:

12 Standards and Interoperability

The character set of all text exports is UTF-8. Timestamps of response data are in UTC; the activity log states the time zone used in its header row. The participant_id is the same identifier in all response exports; in the long format via Data > Export Data it is held in resp.id (Section 4(3)). In the input data of the estimation (Section 4(4)) and in the HB results (Section 8, column Respondent), by contrast, the respondent identifier is a consecutive number of the respective run; the mapping to the participant_id is held in the mapping files of the project backup (Section 6.2). These identifiers allow wide format, long format, raw data and HB results to be joined.