Exploring variables and carriers
Before you build a table, a ranking or a target you need the codes of the variables, categories and carriers of a survey. The API gives you two ways to get them.
| Need | Operation |
|---|---|
| The whole variables tree, once | GET /api/v2/survey/{surveyCode}/variables |
| The whole carriers tree, once | GET /api/v2/survey/{surveyCode}/carriers |
| Browse a tree level by level, search it by label, or look up codes | POST /api/v2/survey/{surveyCode}/tree/query |
| The user variables and targets of a workspace | POST /api/v2/workspace/{workspaceId}/survey/{surveyCode}/tree/query/custom, or the plain lists GET .../user-vars and GET .../targets |
1. The complete lists
GET .../variables and GET .../carriers return the whole tree in one response, nested through items:
- Variables: folders (
type: FOLDER) contain sub-folders or variables (type: VAR); variables contain their categories (type: CATEGORY). - Carriers: folders contain sub-folders or carriers (
type: CARRIER); carriers are leaves. idis the code used by the rest of the API. Note the different property names: the categories of a variable are initemshere and incategoriesin a table request.subtypetells how a variable is measured:SINGLE,MULTIPLE,NUMERIC,REAL,LOGIC,TEXTorFREQUENCY. It can be absent.- A carrier has no
subtype. ItsaudienceModelis the audience model the survey uses for it (STANDARD,DIGITAL_MEASUREMENT,POISSON,ITALIAN_DIARY_INTERNETorITALIAN_DIARY) and is informative. - Properties without a value are omitted.
There is no pagination and no truncation, so the payload can be large. Send Accept-Encoding: gzip. The trees change rarely (when the survey is reloaded): cache them on your side instead of calling the operation before every table.
User variables saved in your workspaces are not part of the variables tree: list them with GET .../user-vars.
2. The tree query
POST /api/v2/survey/{surveyCode}/tree/query asks only for the nodes you need. Use it to build tree pickers and type-ahead searches, and to resolve codes to labels.
The body has a method, a treeType (VARIABLES or CARRIERS, the carriers tree, or both) and optional anchors and filters:
| Goal | method.type | Anchors | Returns |
|---|---|---|---|
| Load the first level | NODE | none | The root nodes |
| Fetch given nodes | NODE | nodesId | The anchor nodes themselves |
| Expand a node | NODE_CHILD | nodesId | The direct children of each anchor |
| Load a whole branch | NODE_HIERARCHY | nodesId | All descendants of each anchor, up to 6 levels below |
| Search and reveal the path | NODE_PARENTS | text and/or nodesId | The matching nodes and their ancestors, up to 6 levels above |
| Ancestors and descendants | NODE_FULL_HIERARCHY | nodesId | Ancestors and descendants of each anchor |
| Flat search or full dump | ALL | none | Every node that passes the filters. To search within a branch, use NODE_HIERARCHY |
With NODE_CHILD, NODE_HIERARCHY, NODE_PARENTS and NODE_FULL_HIERARCHY the anchors themselves are left out unless includeSelected is true.
ALL takes no anchors: a request with ALL and nodesId or nodes is rejected with 400 AE_ERR_400. To fetch given nodes send NODE; to search under a node send NODE_HIERARCHY with the anchor and text or types.
Load the first level of the variables tree, then expand a folder with the id of a node of the previous answer:
{ "method": { "type": "NODE" }, "treeType": ["VARIABLES"] }
{ "method": { "type": "NODE_CHILD" }, "treeType": ["VARIABLES"], "nodesId": ["kT9wQ2mZRo-3vYb7HcX1aA"] }
Search variables by label, and see where each match lives:
{ "method": { "type": "NODE_PARENTS" }, "treeType": ["VARIABLES"], "text": "age" }
Search carriers:
{ "method": { "type": "ALL" }, "treeType": ["CARRIERS"], "types": ["CARRIER"], "text": "channel" }
2.1. Filtering
typeskeeps only nodes of those types, including the ancestors returned byNODE_PARENTS.subtypeskeeps only nodes with those subtypes. WithNODE_PARENTSit selects the matching nodes and their ancestors are still returned.textkeeps the nodes whose label contains the text. Spaces and the characters+ * ^ - ( ) ! : [ ] \ / ? & ~ .are ignored intext; a text made only of those characters matches nothing.
2.2. Identifiers: id or code
Every node has an id and a code:
idis an opaque identifier of the node in this tree, for navigation only. It depends on the survey and on the position and label of the node, so it can change when the survey is reloaded.codeis the identifier used by the rest of the API: the variable id in table axes, the category id in TGL, the carrier id in rankings, evaluations and Reach. Store codes, not node ids. Codes are not unique: category codes such asD1repeat under different variables.
By default, nodesId holds node ids (searchField ID). Set searchField to CODE to pass codes instead (for example ["SEX", "EDA1"]), or to LABEL to pass exact labels:
{ "method": { "type": "NODE" }, "treeType": ["VARIABLES"], "searchField": "CODE", "nodesId": ["SEX", "EDA1"] }
2.3. The response
- By default the response is a flat array sorted by
order(tree order; with two tree types, one list after the other). Rebuild the hierarchy withparentId, or read the ancestry frompathIds(ids from the root down to the node, separated by||) andpath(labels). - With the query parameter
treeMode=truethe nodes are nested underchilds. In this modepath,databasesandtreeTypeare omitted. - A carrier node (
type: CARRIER) has nosubtype: it carriesaudienceModeland, when the survey defines it, acarrierInfoobject withmedium,info,time,dayandduration. - Properties without a value are omitted.
2.4. Limits
- A query that matches more than 3,000 nodes is answered with
206 Partial Contentand the first 3,000 nodes in tree order, always as a flat list (treeModeis ignored). Narrow the query with an anchor,typesortext, and repeat it. NODE_HIERARCHY,NODE_PARENTSandNODE_FULL_HIERARCHYtraverse at most 6 levels.TREE_ERR_404means that no node matches the query. Treat it as an empty result.
3. From a node to a request
| You have | You put | Where |
|---|---|---|
A VAR node | Its code as id, its subtype, and "type": "VAR" | A variable of a VARIABLES axis of a table |
A CATEGORY node | Its code as id and "type": "CATEGORY" | The categories of that variable, or VARIABLE.CATEGORY in a TGL expression |
A CARRIER node | Its code as id | carriers of a CARRIERS axis, carriers of a ranking, evaluation, response curve or optimization |
A variable of subtype TEXT cannot be tabulated.
4. The custom tree of a workspace
POST /api/v2/workspace/{workspaceId}/survey/{surveyCode}/tree/query/custom works like the survey tree query, for the targets and user variables saved in a workspace, organised in the workspace's folders.
- It has two root folders,
ROOT_FOLDER_TARGETandROOT_FOLDER_USER_VAR, whoseidandcodeare these fixed values. Below them there are folders (FOLDER), targets (TARGET_VAR), user variables (CUSTOM_VAR) and, forSINGLEandMULTIPLEuser variables, their categories (CUSTOM_CAT). - For every custom node,
idandcodehold the same value: the element id. Put the id of aCUSTOM_VAR(with itssubtype) or of aTARGET_VARin aVARIABLESaxis of a table. - Only the
VARIABLEStree has custom elements: a request whose only tree type isCARRIERSreturnsTREE_ERR_404. - The anchors in
nodesIdare left out of the result with every method, unlessincludeSelectedistrue. To fetch given elements, sendNODEwithincludeSelected: true. NODE_FULL_HIERARCHYis not supported.NODE_CHILDandNODE_HIERARCHYrequirenodesId.- The whole result is always returned: there is no
206. - With the query parameter
validate=true(the default), each user variable and target is checked against the variables ofsurveyCode: elements that cannot be used with the survey are left out, and elements that can be used in part come withstatus: INVALIDunlessexcludeInvalidistrue. Readstatusin flat mode only.
5. Errors
Status and errorCode | Cause |
|---|---|
400 TREE_ERR_404 | No node matches the query. |
400 AE_ERR_400 | method is present but has no type. |
400 AE_ERR_400 | method.type is ALL and nodesId or nodes is not empty. Use NODE to fetch given nodes or NODE_HIERARCHY to search under a node. |
400 | method or treeType is missing (validation error). |
400 AE_ERR_401 | method.type, treeType, types or searchField has an unknown value. The message names the field, with its position in a list, and lists the valid values. Values are case-sensitive. |
400 E400 | The body is not valid JSON. |
401 E401 | The X-API-Key header is missing. |
403 AE_ERR_415 | The survey is not available to you: not contracted, disabled, being loaded or non-existent. |
500 GEN_ERR_500 | Unexpected error. |