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
surveyCodeis thecodeof a survey returned byGET /api/v2/users/surveys.
Response
- An array of root items, usually folders (
type: FOLDER). Folders contain sub-folders or variables (type: VAR) initems; variables contain their categories (type: CATEGORY) initems. idis the code used by the rest of the API. Put a variableid(for exampleSEX) in aVARIABLESaxis ofPOST /api/v2/table/{surveyCode}, and its category ids in that variable'scategoriesarray. Note the different property name:itemshere,categoriesin the table request.- Category ids (for example
D1) are unique only within their variable. In TGL expressions a category is writtenVARIABLE.CATEGORY, for exampleSEX.D1. subtypetells how a variable is measured:SINGLE(one category per respondent),MULTIPLE(several categories per respondent),NUMERIC,REAL,LOGIC,TEXTorFREQUENCY. It can be absent. Folders and categories have no subtype.TEXTvariables 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
| Status | errorCode | When |
|---|---|---|
| 400 | TREE_ERR_404 | The survey has no variables tree. |
| 401 | E401 | The X-API-Key header is missing or empty. |
| 403 | AE_ERR_415 | The survey is not available to you: not contracted, disabled, being loaded, or non-existent. The same answer is given in every case. |
| 500 | GEN_ERR_500 | Unexpected error. |
Request
Responses
- 200
- 400
- 401
- 403
- 500
The variables tree of the survey, as an array of root items (usually folders) with their descendants nested in items.
The survey has no variables tree (TREE_ERR_404).
The X-API-Key header is missing or empty.
The survey is not available to the user: not contracted, disabled, being loaded or non-existent. The answer is the same in every case (AE_ERR_415).
Unexpected error.