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
surveyCodeis thecodeof a survey returned byGET /api/v2/users/surveys.- Anchor ids (
nodesId) are, by default, theidof nodes returned by a previous call to this operation.
Choosing the method (method.type)
| 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.
Identifying nodes
- Every node has an
idand acode.idis 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.codeis 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 asD1repeat under different variables. - By default
nodesIdholds nodeids (searchFieldID). SetsearchFieldtoCODEto pass codes instead (for example["SEX", "EDA1"]), or toLABELto pass exact labels.searchFielddoes not affecttext. nodesholds{id, uuid}pairs, whereidis a code. When present it replacesnodesIdwith those codes, so send it together withsearchField: CODE.
Filtering
typeskeeps only nodes of those types. It applies to every returned node, including the ancestors returned byNODE_PARENTS.subtypeskeeps only nodes with those subtypes. WithNODE_PARENTSit selects the matching nodes, and their ancestors are still returned; with the other methods, nodes without a subtype (folders, categories) are dropped.textkeeps nodes whose label contains the text. Spaces and the characters+ * ^ - ( ) ! : [ ] \ / ? & ~ .are ignored intext; a text made only of those characters matches nothing. WithNODE_PARENTSthe matches come with their ancestors; withALLonly 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,excludeInvalidandlanguagehave 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 withparentId, or read the ancestry frompathIds(ids from the root down to the node itself, separated by||) andpath(labels separated by a backslash). - With
treeMode=truethe nodes are nested underchilds; a node whose parent is not part of the result is placed at the top level. In this modepath,databasesandtreeTypeare omitted andstatusis alwaysVALID. - 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.
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 Contentand the first 3,000 nodes in tree order, always as a flat list (treeModeis ignored). Narrow the query with an anchor,typesortextand repeat it. NODE_HIERARCHY,NODE_PARENTSandNODE_FULL_HIERARCHYtraverse at most 6 levels.
Errors
| Status | errorCode | When |
|---|---|---|
| 400 | TREE_ERR_404 | No node matches the query (also when text has only ignored characters). Treat it as an empty result. |
| 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 | AE_ERR_400 | treeType is an empty list. |
| 400 | AE_ERR_412 | treeType has a null item; the message gives its position. |
| 400 | validation error | method or treeType is missing. |
| 400 | E400 | The body is not valid JSON. |
| 400 | AE_ERR_401 | method.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. |
| 401 | E401 | The X-API-Key header is missing or empty. |
| 403 | AE_ERR_415 | The survey is not available to you. |
| 500 | GEN_ERR_500 | Unexpected error. |
Request
Responses
- 200
- 206
- 400
- 401
- 403
- 500
The nodes that match the query: a flat array sorted by order, or a nested array when treeMode=true.
The query matched more than 3,000 nodes. The body holds the first 3,000 nodes in tree order, always as a flat list (treeMode is ignored). Narrow the query and repeat it.
The request cannot be answered. TREE_ERR_404: no node matches the query. AE_ERR_400: method has no type, ALL is sent with nodesId or nodes, or treeType is empty. AE_ERR_412: treeType has a null item. E400: the body is not valid JSON. AE_ERR_401: an enumerated field (method.type, treeType, types or searchField) has an unknown value; the message lists the valid ones. A missing method or treeType is also answered with 400.
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.