Skip to main content

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​

typePayloadUse it with
TABULATIONtable: a table request (tableType, dimensions, extraParams, target, targetBase, weeks, weight)POST /api/v2/table/{surveyCode}
REACH_TABLEtable: a table request with tableType REACH_TABLE, REACH_DUPLICATION or REACH_TREND, with its targetMedia and diaryFilters when they were savedPOST /api/v2/table/{surveyCode}, POST /api/v2/table/{surveyCode}/html or POST /api/v2/reach/{surveyCode}, unchanged
TARGETtarget: the target's id, label and TGL expression (filterTgl), plus its dates and workspaceId when availabletarget of table, ranking, evaluation and optimization requests
USER_VARNone; only the element metadataGET /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​

  • surveyCode is 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 that surveyCode to get the figures of the element: in a REACH_TREND the survey of the path acts as the active survey of the comparison, so another survey can give other figures.
  • The returned table carries the dimensions, the table type, extraParams, the saved target and, when it was saved applied, the targetBase. Each one comes with id when it was saved by id, with filterTgl when there is a saved TGL expression or when its saved conditions can be written as one, and with label when there is one. With resolve=TGL, a target or a base saved by id also returns its filterTgl. A target or a base that cannot be returned in one of these forms is marked in notReproducible (see below).
  • weeks and weight of a TABULATION or REACH_TABLE are 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. A TREND or REACH_TREND carries them in each survey wave of its SOURCES axis, with the selected of 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_DUPLICATION or REACH_TREND) carries its targetMedia and its diaryFilters when they were saved. A folder of the target media comes with type FOLDER and a carrier with type CARRIER; 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 its TIME_DIARY_EDGE axes, so no Reach setting that changes the figures is left out.
  • A REACH_TREND comes complete: type is REACH_TABLE, table.tableType is REACH_TREND, and dimensions carries its SOURCES and DIFFERENCES axes. A SOURCES axis saved as a group of surveys comes expanded, one survey wave per member with its weeks and weighting, and without the group.
  • extraParams is returned as it was saved, trendCategoriesMode included.
  • To build the request, the platform evaluates the saved table. Expect the latency of a calculation, once per survey wave in a TREND or REACH_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:

fieldreasonWhat happened
target, targetBaseNEGATIONThe 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, targetBaseWEIGHTA box or a reference of the definition carries a weight.
target, targetBaseNESTEDThe definition has nested sets or references that cannot be expanded.
target, targetBaseEMPTYThe definition has no conditions.
target, targetBaseOTHERAny other reason, or the platform did not report one.
diaryEdgeGROUPED_ITEMAn item of a CUSTOM_DIARY_EDGE axis grouped several values (for example Monday to Friday), and it was left out of the axis.
diaryEdgeTOTAL_ITEMA 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 target or targetBase comes in table with its label only. Sent back unchanged, it is rejected with 400 (AE_ERR_405) and the message names the field: the table is never calculated over the whole population. Define it again, by id or with filterTgl, 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.
  • notReproducible is 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 subtype SINGLE or MULTIPLE keeps its id and returns a tgl in each of its CUSTOM_CAT categories. A JOINT returns its ids, and the categories it joins come back too when they are hidden (or, in PLANES, not selected), with hidden: true when they are hidden. They are not returned in split axes.
  • A saved target, in an axis or as the target or targetBase of the table, keeps its id and also returns filterTgl. In a calculation, filterTgl wins over id.
  • A target or a base saved with its conditions only gets its filterTgl with or without resolve.
  • Send them back unchanged. When every CUSTOM_CAT category of a user variable has a tgl, the calculation uses them and does not look the variable up by id. If one is missing, the variable is looked up by id as 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 answers 200. This covers numeric user variables (NUMERIC, REAL, FREQUENCY), cluster variables, categories with a weight or negated as a whole, references to variables that are not SINGLE or MULTIPLE, and JOINT categories with hidden members in split axes. Sending such a table to a user who cannot see the variable fails as it does without resolve.
  • The conditions are a snapshot: if the variable is edited afterwards, the table keeps the old definition until it is read again.
  • resolve does not change the response of TARGET and USER_VAR elements. Blank means absent.

Errors​

StatuserrorCodeWhen
400AE_ERR_401resolve has a value other than TGL.
400WS_ERR_403The workspace is neither owned by nor shared with the caller.
400VA_ERR_101(TABULATION, REACH_TABLE) The variables of the element do not exist in the survey currently active in the workspace.
400TB_ERR_104(TABULATION) No variable of the element is valid in the survey currently active in the workspace.
401E401The X-API-Key header is missing or empty.
403AE_ERR_407(TARGET) The target exists but is not visible to the caller.
404AE_ERR_404No tabulation, Reach table, target or user variable with elementId exists in the workspace.
404AE_ERR_406(TARGET) The target cannot be resolved.
500GEN_ERR_500Unexpected error.

Request​

Responses​

The element and, for tables and targets, its reusable request.