Data Format

Overview

The Required elements at root level:

 "CaseData" – which is the data

 "MetaData" – which is the description of the data

 "ImportContext" – which has settings for the system


All fields are case sensitive, there must not be any duplicates.


This document describes the three elements in order.


Case Data

Case Data Using JSON


There are three default fields for each respondent:

RespondentID of type OpenNumeric

ResponseDate of type DateTime

Weight of type OpenNumeric


The names of the default fields can be over written in the import context. Default values can be applied for response date and weight suitable when all respondents share the same values.


So, assuming we are setting ID, date and weight per respondent, the first three elements in a respondents case data would normally be:

"RespondentID": "1","ResponseDate": "2021-12-12","Weight": "0.9"


The order of the fields doesn't matter in either the case or metadata


Then the values for all the variables that are defined in the metadata as key value pairs.

Example Case Data:

"CaseData":[
    {"RespondentID": "1","ResponseDate": "2021-12-12","Weight": "0.9","RespondentAge": "35","PetName": "Fido","Country": [ "1" ],"Brands": [ "1", "2" ],"Scale":["5"]},
    {"RespondentID": "2","ResponseDate": "2021-12-13","Weight": "1.1","RespondentAge": "32","PetName": "Rover","Country": [ "2" ],"Brands": [ "2" ],"Scale":["4"]},
  {"RespondentID": "3","ResponseDate": "2021-12-14","Weight": "1","RespondentAge": "21","PetName": "Tyson","Country": [ "2" ],"Brands": [ "2", "3" ],"Scale":["3"]},
  {"RespondentID": "4","ResponseDate": "2021-12-15","Weight": "1","RespondentAge": "53","PetName": "Rocky","Country": [ "3" ],"Scale":["2"]}],



Case Data using CSV

Case data can also be uploaded via a CSV file. This should be formatted according to the RFC 4180

standard. 

The first line should be the question codes.


Use CSV case data for large data sets, the file sizes are smaller.


Commas and new lines are supported in fields enclosed in double quotes:

”1”,”This is the first line

this the second line”,”3”


If a double quote is to be imported it must be preceeded by a double quote.

"1","This field contains a ""quoted"" section","3"

The string variable aboce would be imported as:

This field contains a "quoted" section


Using double quotes is not obligatory if none of the above considerations apply.


Uploading data in CSV is a two stage process. 

First POST the file via the rest method

/api/v1/project/nnnnnn/interactive_import/upload –

Eg using c#

request.AddParameter("multipart/form-data; boundary=----
WebKitFormBoundary7MA4YWxkTrZu0gW", "------
WebKitFormBoundary7MA4YWxkTrZu0gW\r\nContent-Disposition: form-data; name=\"\";
filename=\"exampleDataApiCSV.csv\"\r\nContent-Type: text/csv\r\n\r\n\r\n------
WebKitFormBoundary7MA4YWxkTrZu0gW--", ParameterType.RequestBody);


Then call the import method adding the file identifier which is the response to the upload method:

"tempFileGuid": "03266da5-c9a0-41ce-8fa1-7dc18e63e33e",
"fileName": "exampleDataApiCSV.csv"



Metadata

Metadata describes the data, variable types, answer codes and values. The required elements as per

case data, a RespondentID, ResponseDate and Weight. Each element needs to have Code, Text, Type

and optionally the AnswerAlternatives array.


Example metadata demonstrating different question types of variables :

"MetaData":[  
  {"Code":"RespondentID","Text":"RespondentID","Type":"OpenNumeric","AnswerAlternative":null},
  {"Code":"ResponseDate","Text":"ResponseDate","Type":"DateTime","AnswerAlternative":null},
  {"Code":"Weight","Text":"Weight","Type":"OpenNumeric","AnswerAlternative":null},
  {"Code":"RespondentAge","Text":"How old are you?","Type":"OpenNumeric","AnswerAlternative":null},
  {"Code":"PetName","Text":"What is the name of your pet?","Type":"OpenString","AnswerAlternative":null},
  {"Code":"Country","Text":"Where you are from?","Type":"SingleChoice",
    "AnswerAlternatives":[{"Code":"1","Text":"UK"},{"Code":"2","Text":"Sweden"},{"Code":"3","Text":"Germany"}]},
  {"Code":"Brands","Text":"Which brands do you use?","Type":"MultiChoice",
    "AnswerAlternatives":[{"Code":"1","Text":"Apple"},{"Code":"2","Text":"Samsung"},{"Code":"3","Text":"HP"},{"Code":"4","Text":"Asus"}]},
  {"Code":"Scale","Text":"Enter a rating(1to5)?","Type":"SingleChoiceScale",
    "AnswerAlternatives":[{"Code":"1","Text":"1"},{"Code":"2","Text":"2"},{"Code":"3","Text":"3"},{"Code":"4","Text":"4"},{"Code":"5","Text":"5"}]}]


Limits for field sizes:
Question code is limited to 50 chars, Question text is 500 chars.
Answer code is of data type int, i.e. a 4 byte signed integer, Answer text 500 chars.


Code

Question codes are limited in length to 50 characters and if it is required that they will be exported in SPSS format should start with a letter, although numeric codes are supported.


Type

Valid Types are:

OpenNumeric

OpenString

DateTime

SingleChoice

SingleChoiceScale

MultiChoice


AnswerAlternatives

This an element with an array of Code and Text fields. 


ImportContext

Example import context:

  "ImportContext":{"ImportType":2,"ImportSource":7,"StackedData":false,"OverwriteMetadata":false,"UpdateData":false,"ActiveMappingId":0,"TempFileGUID":"","FileName":""}


The following section describes the values supported in the import context-


ImportType

”1” for case data only, ”2” for case and meta data. With type ”1” the metadata element must still be sent with the mandatory RespondentID, ResponseDate and Weight elements. No other metadata information should be sent.


ImportSource

Valid values are:

 Xml = 1, (Deprecated)

 Spss = 2,

 TripleS = 3,

 Excel = 4,

 Unicom = 5,

 Json = 6,

 DataApiCSV = 7


For the Data Import API, currently, the value will be 6 for regular imports and 7 for the CSV case data.


Stacked Data

if the data set is a loop or grid associated with existing respondents set this to true


OverwriteMetadata

set to true if metadata should be overwritten


UpdateData

set to true if this data should be treated as an update to an existing dataset rather than new data.


ActiveMappingId

The metadata mapping to use for the imported data. In most cases this will not be relevant for the data API.


AnswerBlockShare

How to group answers in answer blocks.

Allowed values:

"Smart detection of similar answer lists" (Default value) compare texts in answer list to create answer

blocks that have sets of matching texts.

"Identical answer lists" Use same answer block when all texts and codes match

"No sharing" create new answer block for each question, every question will have its own answer block


TempFileGUID + FileName

Used in uploading CSV data - see above


RespondentIDVariable

Set the respondent id variable name, defaults to RespondentId


ResponseDateVariable

Use this to over ride the default ”ResponseDate” variable. Must be a date variable.


WeightVariable

Set variable name to use for weight if not ”Weight” – must be open numeric


GlobalResponseDate

Set a default response date for all respondents


GlobalWeight

Set a weight for all respondents


DateFormat

Set the date format string to be applied when reading dates.

For example: "DateFormat": "yyyy-M-d" to support dates in 2019-12-31 format.


ExcludedAnswerCodes

a comma separated list of values to exclude from import.