Skip to main content

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.

NeedOperation
The whole variables tree, onceGET /api/v2/survey/{surveyCode}/variables
The whole carriers tree, onceGET /api/v2/survey/{surveyCode}/carriers
Browse a tree level by level, search it by label, or look up codesPOST /api/v2/survey/{surveyCode}/tree/query
The user variables and targets of a workspacePOST /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.
  • id is the code used by the rest of the API. Note the different property names: the categories of a variable are in items here and in categories in a table request.
  • subtype tells how a variable is measured: SINGLE, MULTIPLE, NUMERIC, REAL, LOGIC, TEXT or FREQUENCY. It can be absent.
  • A carrier has no subtype. Its audienceModel is the audience model the survey uses for it (STANDARD, DIGITAL_MEASUREMENT, POISSON, ITALIAN_DIARY_INTERNET or ITALIAN_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:

Goalmethod.typeAnchorsReturns
Load the first levelNODEnoneThe root nodes
Fetch given nodesNODEnodesIdThe anchor nodes themselves
Expand a nodeNODE_CHILDnodesIdThe direct children of each anchor
Load a whole branchNODE_HIERARCHYnodesIdAll descendants of each anchor, up to 6 levels below
Search and reveal the pathNODE_PARENTStext and/or nodesIdThe matching nodes and their ancestors, up to 6 levels above
Ancestors and descendantsNODE_FULL_HIERARCHYnodesIdAncestors and descendants of each anchor
Flat search or full dumpALLnoneEvery 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​

  • types keeps only nodes of those types, including the ancestors returned by NODE_PARENTS.
  • subtypes keeps only nodes with those subtypes. With NODE_PARENTS it selects the matching nodes and their ancestors are still returned.
  • text keeps the nodes whose label contains the text. Spaces and the characters + * ^ - ( ) ! : [ ] \ / ? & ~ . are ignored in text; a text made only of those characters matches nothing.

2.2. Identifiers: id or code​

Every node has an id and a code:

  • id is 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.
  • code is 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 as D1 repeat 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 with parentId, or read the ancestry from pathIds (ids from the root down to the node, separated by ||) and path (labels).
  • With the query parameter treeMode=true the nodes are nested under childs. In this mode path, databases and treeType are omitted.
  • A carrier node (type: CARRIER) has no subtype: it carries audienceModel and, when the survey defines it, a carrierInfo object with medium, info, time, day and duration.
  • Properties without a value are omitted.

2.4. Limits​

  • A query that matches more than 3,000 nodes is answered with 206 Partial Content and the first 3,000 nodes in tree order, always as a flat list (treeMode is ignored). Narrow the query with an anchor, types or text, and repeat it.
  • NODE_HIERARCHY, NODE_PARENTS and NODE_FULL_HIERARCHY traverse at most 6 levels.
  • TREE_ERR_404 means that no node matches the query. Treat it as an empty result.

3. From a node to a request​

You haveYou putWhere
A VAR nodeIts code as id, its subtype, and "type": "VAR"A variable of a VARIABLES axis of a table
A CATEGORY nodeIts code as id and "type": "CATEGORY"The categories of that variable, or VARIABLE.CATEGORY in a TGL expression
A CARRIER nodeIts code as idcarriers 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_TARGET and ROOT_FOLDER_USER_VAR, whose id and code are these fixed values. Below them there are folders (FOLDER), targets (TARGET_VAR), user variables (CUSTOM_VAR) and, for SINGLE and MULTIPLE user variables, their categories (CUSTOM_CAT).
  • For every custom node, id and code hold the same value: the element id. Put the id of a CUSTOM_VAR (with its subtype) or of a TARGET_VAR in a VARIABLES axis of a table.
  • Only the VARIABLES tree has custom elements: a request whose only tree type is CARRIERS returns TREE_ERR_404.
  • The anchors in nodesId are left out of the result with every method, unless includeSelected is true. To fetch given elements, send NODE with includeSelected: true.
  • NODE_FULL_HIERARCHY is not supported. NODE_CHILD and NODE_HIERARCHY require nodesId.
  • 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 of surveyCode: elements that cannot be used with the survey are left out, and elements that can be used in part come with status: INVALID unless excludeInvalid is true. Read status in flat mode only.

5. Errors​

Status and errorCodeCause
400 TREE_ERR_404No node matches the query.
400 AE_ERR_400method is present but has no type.
400 AE_ERR_400method.type is ALL and nodesId or nodes is not empty. Use NODE to fetch given nodes or NODE_HIERARCHY to search under a node.
400method or treeType is missing (validation error).
400 AE_ERR_401method.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 E400The body is not valid JSON.
401 E401The X-API-Key header is missing.
403 AE_ERR_415The survey is not available to you: not contracted, disabled, being loaded or non-existent.
500 GEN_ERR_500Unexpected error.

See Errors and troubleshooting.