Get a workspace element as a reusable request
GET/api/v2/workspace/:workspaceId/element/:elementId
Returns a saved workspace element converted to the request format of this API, so that you can inspect it, modify it and send it again.
The element's results are not returned.
Get workspaceId from GET /api/v2/workspaces and elementId from the element lists of GET /api/v2/workspace/{workspaceId}.
What you get, by element type
type | Payload | Use it with |
|---|---|---|
TABULATION | table: a table request (tableType, dimensions, extraParams, target, targetBase, weeks, weight) | POST /api/v2/table/{surveyCode} |
REACH_TABLE | table: a table request with tableType REACH_TABLE, REACH_DUPLICATION or REACH_TREND, with its targetMedia and diaryFilters when they were saved | POST /api/v2/table/{surveyCode}, POST /api/v2/table/{surveyCode}/html or POST /api/v2/reach/{surveyCode}, unchanged |
TARGET | target: the target's id, label and TGL expression (filterTgl), plus its dates and workspaceId when available | target of table, ranking, evaluation and optimization requests |
USER_VAR | None; only the element metadata | GET /api/v2/workspace/{workspaceId}/survey/{surveyCode}/user-vars |
Saved studies (rankings, evaluations, breakdowns, duplications) are not supported and return 404.
Before you send a table again
surveyCodeis the survey currently active in the workspace, not necessarily the survey the element was saved with, and the table was read with it. Send the request to thatsurveyCodeto get the figures of the element: in aREACH_TRENDthe survey of the path acts as the active survey of the comparison, so another survey can give other figures.- The returned
tablecarries the dimensions, the table type,extraParams, the savedtargetand, when it was saved applied, thetargetBase. Each one comes withidwhen it was saved by id, withfilterTglwhen there is a saved TGL expression or when its saved conditions can be written as one, and withlabelwhen there is one. Withresolve=TGL, a target or a base saved byidalso returns itsfilterTgl. A target or a base that cannot be returned in one of these forms is marked innotReproducible(see below). weeksandweightof aTABULATIONorREACH_TABLEare the effective ones: when the element has none saved, or the survey no longer has the saved one, they are the first week and the default weighting of the survey, the ones the TOM web application shows. ATRENDorREACH_TRENDcarries them in each survey wave of itsSOURCESaxis, with theselectedof each wave, and the other table types do not carry them. In a Reach table they are validated when the table is sent again, but they do not change the Reach figures.- A Reach table (
REACH_TABLE,REACH_DUPLICATIONorREACH_TREND) carries itstargetMediaand itsdiaryFilterswhen they were saved. A folder of the target media comes withtypeFOLDERand a carrier withtypeCARRIER; media saved in several groups come in a single list, in their saved order. A diary filter comes once per edge filtered explicitly, with the codes of its values. The time configuration of a Reach table is in itsTIME_DIARY_EDGEaxes, so no Reach setting that changes the figures is left out. - A
REACH_TRENDcomes complete:typeisREACH_TABLE,table.tableTypeisREACH_TREND, anddimensionscarries itsSOURCESandDIFFERENCESaxes. ASOURCESaxis saved as a group of surveys comes expanded, one survey wave per member with its weeks and weighting, and without the group. extraParamsis returned as it was saved,trendCategoriesModeincluded.- To build the request, the platform evaluates the saved table. Expect the latency of a calculation, once per survey wave in a
TRENDorREACH_TREND, and a calculation error if the saved definition is no longer valid for the active survey.
Parts that cannot be returned as they were saved (notReproducible)
notReproducible lists, outside table, what the request cannot carry as it was saved. Each entry has a field and a reason:
field | reason | What happened |
|---|---|---|
target, targetBase | NEGATION | The whole definition is negated, or it negates a numeric condition. A group or a category negated with NOT is written in filterTgl and is not marked. |
target, targetBase | WEIGHT | A box or a reference of the definition carries a weight. |
target, targetBase | NESTED | The definition has nested sets or references that cannot be expanded. |
target, targetBase | EMPTY | The definition has no conditions. |
target, targetBase | OTHER | Any other reason, or the platform did not report one. |
diaryEdge | GROUPED_ITEM | An item of a CUSTOM_DIARY_EDGE axis grouped several values (for example Monday to Friday), and it was left out of the axis. |
diaryEdge | TOTAL_ITEM | A CUSTOM_DIARY_EDGE or TIME_DIARY_EDGE axis shows its total item, which a request cannot ask for: sent back, the table has that row or column fewer. |
- A marked
targetortargetBasecomes intablewith itslabelonly. Sent back unchanged, it is rejected with400(AE_ERR_405) and the message names the field: the table is never calculated over the whole population. Define it again, byidor withfilterTgl, before you send the table. - A base that is not applied is neither returned nor marked.
- A grouped item is marked once, however many axes had one. The other items of the axis are returned as usual; an axis left without items is left out, and so is a dimension left without axes. Sent back, the table is calculated without the grouped item.
notReproducibleis omitted when there is nothing to mark.
Reading a table to send it to another user (resolve=TGL)
A saved table refers to its user variables (CUSTOM_VAR) and saved targets (TARGET_VAR) by id, so only a user who can see them can calculate it. With resolve=TGL on a TABULATION or REACH_TABLE element, the response also carries their conditions; it acts on every table type except TREND, and on any Reach table, REACH_TREND included. You can then send the table unchanged to POST /api/v2/table/{surveyCode}, POST /api/v2/table/{surveyCode}/html or POST /api/v2/reach/{surveyCode}, also with the key of a user who cannot see those variables.
- A user variable with
subtypeSINGLEorMULTIPLEkeeps itsidand returns atglin each of itsCUSTOM_CATcategories. AJOINTreturns itsids, and the categories it joins come back too when they are hidden (or, inPLANES, not selected), withhidden: truewhen they are hidden. They are not returned in split axes. - A saved target, in an axis or as the
targetortargetBaseof the table, keeps itsidand also returnsfilterTgl. In a calculation,filterTglwins overid. - A target or a base saved with its conditions only gets its
filterTglwith or withoutresolve. - Send them back unchanged. When every
CUSTOM_CATcategory of a user variable has atgl, the calculation uses them and does not look the variable up byid. If one is missing, the variable is looked up byidas before, with no error. - The conditions are resolved with the permissions of the key of this request: only what that user can see is resolved.
- A variable that cannot be written as TGL comes back without
tgl, and the request still answers200. This covers numeric user variables (NUMERIC,REAL,FREQUENCY), cluster variables, categories with a weight or negated as a whole, references to variables that are notSINGLEorMULTIPLE, andJOINTcategories with hidden members in split axes. Sending such a table to a user who cannot see the variable fails as it does withoutresolve. - The conditions are a snapshot: if the variable is edited afterwards, the table keeps the old definition until it is read again.
resolvedoes not change the response ofTARGETandUSER_VARelements. Blank means absent.
Errors
| Status | errorCode | When |
|---|---|---|
| 400 | AE_ERR_401 | resolve has a value other than TGL. |
| 400 | WS_ERR_403 | The workspace is neither owned by nor shared with the caller. |
| 400 | VA_ERR_101 | (TABULATION, REACH_TABLE) The variables of the element do not exist in the survey currently active in the workspace. |
| 400 | TB_ERR_104 | (TABULATION) No variable of the element is valid in the survey currently active in the workspace. |
| 401 | E401 | The X-API-Key header is missing or empty. |
| 403 | AE_ERR_407 | (TARGET) The target exists but is not visible to the caller. |
| 404 | AE_ERR_404 | No tabulation, Reach table, target or user variable with elementId exists in the workspace. |
| 404 | AE_ERR_406 | (TARGET) The target cannot be resolved. |
| 500 | GEN_ERR_500 | Unexpected error. |
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 500
The element and, for tables and targets, its reusable request.
The workspace is neither owned by nor shared with the caller (WS_ERR_403), the variables of the element do not exist in the survey currently active in the workspace (VA_ERR_101), no variable of a tabulation is valid in that survey (TB_ERR_104), resolve has a value other than TGL (AE_ERR_401), or the X-API-Key value does not identify a TOM user (TW_ERR_500).
The X-API-Key header is missing or empty.
The target exists but is not visible to the user (AE_ERR_407).
No tabulation, Reach table, target or user variable with elementId exists in the workspace (AE_ERR_404), or the target cannot be resolved (AE_ERR_406).
Unexpected error.