Data Types

TSAPI supports various variable types to represent different kinds of survey questions and data. Understanding these types is essential for correctly interpreting survey data.

Variable Types Overview

Single Response (single)

Single response variables allow the respondent to select exactly one option from a list. These are commonly used for rating scales, yes/no questions, and demographic categories.

Metadata Example

{
  "variableId": "4",
  "type": "single",
  "name": "Q2",
  "label": {
    "text": "Frequency of visit"
  },
  "values": {
    "values": [
      { "valueId": "0", "code": "0", "label": { "text": "No, this is the first visit" } },
      { "valueId": "1", "code": "1", "label": { "text": "I visited before within the year" } },
      { "valueId": "2", "code": "2", "label": { "text": "I visited before that" } }
    ]
  }
}

Interview Data Example

{
  "variableId": "4",
  "data": [
    { "value": "0", "state": "NotSelected" },
    { "value": "1", "state": "Selected" },
    { "value": "2", "state": "NotSelected" }
  ]
}

In this example, the respondent selected option with code "1" ("I visited before within the year"). The state field indicates which option was selected.

Scores

Values can optionally include a score for numeric analysis:

{
  "valueId": "1",
  "code": "1",
  "label": { "text": "Very Good" },
  "score": 2
}

Multiple Response (multiple)

Multiple response variables allow respondents to select multiple options. These are used for "select all that apply" type questions.

Metadata Example

{
  "variableId": "7",
  "type": "multiple",
  "name": "Q5",
  "label": {
    "text": "Attractions visited"
  },
  "values": {
    "values": [
      { "valueId": "1", "code": "1", "label": { "text": "Museum" } },
      { "valueId": "2", "code": "2", "label": { "text": "Gift Shop" } },
      { "valueId": "3", "code": "3", "label": { "text": "Restaurant" } },
      { "valueId": "98", "code": "98", "label": { "text": "Other" } }
    ]
  },
  "maxResponses": 4
}

Interview Data Example

{
  "variableId": "7",
  "data": [
    { "value": "1", "state": "Selected" },
    { "value": "2", "state": "Selected" },
    { "value": "3", "state": "NotSelected" },
    { "value": "98", "state": "NotSelected" }
  ]
}

The respondent visited both the Museum and Gift Shop.

Quantity (quantity)

Quantity variables store numeric values. They can optionally define a valid range.

Metadata Example

{
  "variableId": "5",
  "type": "quantity",
  "name": "Q3",
  "label": {
    "text": "Miles travelled"
  },
  "values": {
    "range": {
      "from": "0",
      "to": "1000"
    }
  }
}

Interview Data Example

{
  "variableId": "5",
  "data": [
    { "value": "26" }
  ]
}

Character (character)

Character variables store text/string values. These are used for open-ended responses, names, and other freeform text.

Metadata Example

{
  "variableId": "11",
  "type": "character",
  "name": "Q8",
  "label": {
    "text": "Other Comments"
  }
}

Interview Data Example

{
  "variableId": "11",
  "data": [
    { "value": "Great experience, would recommend to friends!" }
  ]
}

Date (date)

Date variables store date values in YYYYMMDD format.

Metadata Example

{
  "variableId": "2",
  "type": "date",
  "name": "Q1a",
  "label": {
    "text": "Date of Visit"
  },
  "values": {
    "range": {
      "from": "20220101",
      "to": "20221231"
    }
  }
}

Interview Data Example

{
  "variableId": "2",
  "data": [
    { "value": "20210101" }
  ]
}

The value "20210101" represents January 1, 2021.

Time (time)

Time variables store time values in HHMMSS format (24-hour).

Metadata Example

{
  "variableId": "3",
  "type": "time",
  "name": "Q1b",
  "label": {
    "text": "Time of Visit"
  }
}

Interview Data Example

{
  "variableId": "3",
  "data": [
    { "value": "080000" }
  ]
}

The value "080000" represents 08:00:00 (8:00 AM).

Special Variable Properties

Use Property

The use property indicates special usage for a variable. Common values include:

• serial - A unique respondent/interview identifier

{
  "variableId": "1",
  "type": "quantity",
  "name": "RESPONDENT_ID",
  "use": "serial",
  "label": { "text": "Respondent ID" }
}

valueId vs code

Each value in a categorical variable has two identifiers:

• valueId - System identifier, typically stable and won't change
• code - Human-readable code, used in data tables and exports

While these are often the same, they can differ. Use code when building data tables or creating variables for analysis.

{
  "valueId": "05865984523544415325584520",
  "code": "1",
  "label": { "text": "Very Good" },
  "score": 2
}

Looped Variables

Variables can contain nested loopedVariables - questions that are asked for each response to the parent variable.

{
  "variableId": "7",
  "type": "multiple",
  "name": "Q5",
  "label": { "text": "Attractions visited" },
  "values": { ... },
  "loopedVariables": [
    {
      "variableId": "8",
      "type": "multiple",
      "name": "Q6",
      "label": { "text": "Experience Elements" },
      "loopedVariables": [
        {
          "variableId": "9",
          "type": "single",
          "name": "Q7",
          "label": { "text": "Experience Rating" }
        }
      ]
    }
  ]
}

In this example, Q6 is asked for each attraction selected in Q5, and Q7 is asked for each experience element selected in Q6.

Other Specify Variables

When a categorical variable has an "Other" option, it can have an associatedotherSpecifyVariables array for capturing the open-ended response:

{
  "variableId": "7",
  "type": "multiple",
  "name": "Q5",
  "values": {
    "values": [
      { "valueId": "98", "code": "98", "label": { "text": "Other" } }
    ]
  },
  "otherSpecifyVariables": [
    {
      "parentValueId": "98",
      "variableId": "7other",
      "type": "character",
      "name": "Q5Other",
      "label": { "text": "Other attractions visited" }
    }
  ]
}

Labels

Main Label

Every variable has a main label with the primary text:

"label": {
  "text": "Overall impression",
  "altLabels": []
}

Alternative Labels

Variables can have alternative labels for different contexts, defined in thealtLabels array:

"label": {
  "text": "Overall impression",
  "altLabels": [
    {
      "mode": "interview",
      "text": "What was your impression overall?",
      "languageId": "EN"
    },
    {
      "mode": "analysis",
      "text": "Impression",
      "languageId": "EN"
    }
  ]
}

• interview - Full question text shown to respondents
• analysis - Shorter label for reports and data analysis