Skip to main content

List the variables of a survey

GET 

/api/v2/survey/:surveyCode/variables

Returns the complete variables tree of a survey in one response: the folders, the variables they contain and the categories of each variable.

Use it to discover which variables you can tabulate and to resolve codes to labels. The payload can be large; to load the tree level by level or to search it by label, use POST /api/v2/survey/{surveyCode}/tree/query instead.

Before you call it​

  • surveyCode is the code of a survey returned by GET /api/v2/users/surveys.

Response​

  • An array of root items, usually folders (type: FOLDER). Folders contain sub-folders or variables (type: VAR) in items; variables contain their categories (type: CATEGORY) in items.
  • id is the code used by the rest of the API. Put a variable id (for example SEX) in a VARIABLES axis of POST /api/v2/table/{surveyCode}, and its category ids in that variable's categories array. Note the different property name: items here, categories in the table request.
  • Category ids (for example D1) are unique only within their variable. In TGL expressions a category is written VARIABLE.CATEGORY, for example SEX.D1.
  • subtype tells how a variable is measured: SINGLE (one category per respondent), MULTIPLE (several categories per respondent), NUMERIC, REAL, LOGIC, TEXT or FREQUENCY. It can be absent. Folders and categories have no subtype. TEXT variables cannot be tabulated.
  • Properties without a value are omitted.
  • User variables saved in your workspaces are not included; list them with GET /api/v2/workspace/{workspaceId}/survey/{surveyCode}/user-vars.

Behaviour​

  • The whole tree is returned: there is no pagination and no truncation.
  • Send Accept-Encoding: gzip; the response is then compressed.
  • The tree changes rarely (when the survey is reloaded): cache it on your side instead of calling this operation before every table.

Errors​

StatuserrorCodeWhen
400TREE_ERR_404The survey has no variables tree.
401E401The X-API-Key header is missing or empty.
403AE_ERR_415The survey is not available to you: not contracted, disabled, being loaded, or non-existent. The same answer is given in every case.
500GEN_ERR_500Unexpected error.

Request​

Responses​

The variables tree of the survey, as an array of root items (usually folders) with their descendants nested in items.