Skip to main content

Query the variables or carriers tree

POST 

/api/v2/survey/:surveyCode/tree/query

Queries the variables tree or the carriers tree of a survey on demand.

Instead of downloading a whole tree (see GET /api/v2/survey/{surveyCode}/variables and .../carriers), you ask only for the nodes you need: the first level, the children of a node, a whole branch, or the nodes whose label contains a text together with their ancestors. Use it to build tree pickers and type-ahead searches, and to resolve codes to labels.

Before you call it​

  • surveyCode is the code of a survey returned by GET /api/v2/users/surveys.
  • Anchor ids (nodesId) are, by default, the id of nodes returned by a previous call to this operation.

Choosing the method (method.type)​

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.

Identifying nodes​

  • Every node has an id and a code. id is an opaque identifier of the node in this tree, for navigation only. It is derived from the survey and from the node's position and label, so it can change when the survey is reloaded. code is the identifier used by the rest of the API: variable id in table axes, category id in TGL, 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. searchField does not affect text.
  • nodes holds {id, uuid} pairs, where id is a code. When present it replaces nodesId with those codes, so send it together with searchField: CODE.

Filtering​

  • types keeps only nodes of those types. It applies to every returned node, 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; with the other methods, nodes without a subtype (folders, categories) are dropped.
  • text keeps nodes whose label contains the text. Spaces and the characters + * ^ - ( ) ! : [ ] \ / ? & ~ . are ignored in text; a text made only of those characters matches nothing. With NODE_PARENTS the matches come with their ancestors; with ALL only the matches are returned.
  • Only the survey's own variables and carriers are returned. User variables and targets of a workspace are browsed with POST /api/v2/workspace/{workspaceId}/survey/{surveyCode}/tree/query/custom. excludeCustoms, excludeInvalid and language have no effect on this operation.

Response​

  • By default, 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 itself, separated by ||) and path (labels separated by a backslash).
  • With treeMode=true the nodes are nested under childs; a node whose parent is not part of the result is placed at the top level. In this mode path, databases and treeType are omitted and status is always VALID.
  • 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.

Deprecated names​

The older names are still accepted in requests and are never returned: SOPORTES for treeType CARRIERS, SUPPORT for types CARRIER, and NODE_UUID, NODE_ID and NODE_DESC for searchField ID, CODE and LABEL. Use the current names.

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.

Errors​

StatuserrorCodeWhen
400TREE_ERR_404No node matches the query (also when text has only ignored characters). Treat it as an empty result.
400AE_ERR_400method is present but has no type.
400AE_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.
400AE_ERR_400treeType is an empty list.
400AE_ERR_412treeType has a null item; the message gives its position.
400validation errormethod or treeType is missing.
400E400The body is not valid JSON.
400AE_ERR_401method.type, treeType, types or searchField has an unknown value, or a number instead of a name. The message names the field, with its position in a list, and lists the valid values. Values are case-sensitive.
401E401The X-API-Key header is missing or empty.
403AE_ERR_415The survey is not available to you.
500GEN_ERR_500Unexpected error.

Request​

Responses​

The nodes that match the query: a flat array sorted by order, or a nested array when treeMode=true.