Skip to main content

Table

Calculated table: the typed dimensions, one matrix per calculated plane item in matrixList, and optional diagnostics. Only the dimensions are echoed from the request; the other request fields (tableType, target, dataType, locale, decimals, extraParams) are not returned.

dimensions object[]

The dimensions of the table with their typed axes: ROWS, COLUMNS and/or PLANES. In PLANES, only the selected items are listed, and hidden dimensions are omitted. They can be posted back to calculate the same table.

  • Array [
  • idDimensionId (string)

    Which dimension it is. Send it in upper case.

    Enum ValueDescription
    ROWSItems listed down the table: the first index of table.
    COLUMNSItems listed across the table: the second index of table.
    PLANESItems that select the slice: one matrix for each selected item.

    Possible values: [ROWS, COLUMNS, PLANES]

    axis object[]required

    Axes of the dimension. Required, with at least one axis: an absent or empty list returns 400 AE_ERR_413.

    Possible values: >= 1

  • Array [
  • idstring

    Identifier of the axis. Optional: when omitted, the API assigns the lowest positive integer not already used ("1", "2", ...). Keep it unique within the request: CATEGORIES axes reference it in parentId, and responses use it in matrixList[].items[].axis. In responses, the axes of type CUSTOM_DIARY_EDGE and TIME_DIARY_EDGE return the edge name as id.

    labelstring

    Display label of the axis. Optional in requests; returned in responses, in the language of the user.

    axisType AxisKind (string)required

    Kind of axis; it selects the schema of the object. MEDIA and MEDIA_PLANS appear only in responses.

    Possible values: [VARIABLES, CATEGORIES, STATISTICS, CARRIERS, SOURCES, DIFFERENCES, CUSTOM_DIARY_EDGE, TIME_DIARY_EDGE, MEDIA, MEDIA_PLANS]

    variables object[]required

    Variables of this axis. Required and non-empty. Each variable needs a type: VAR (survey variable), CUSTOM_VAR (user variable), TARGET_VAR (a saved target or a TGL expression used as a variable) or TOTAL. Take ids from GET /api/v2/survey/{surveyCode}/variables, from the user variables of the workspace and from its targets. Omit categories to use all the categories of a categorical variable. selected marks the variable that fixes the slice in a PLANES axis: in PLANES several can be selected (one matrix each), in any other axis more than one returns 400 AE_ERR_404. VAR and CUSTOM_VAR need subtype and id (a VAR with subtype TOTAL needs no id); CUSTOM_VAR accepts the subtypes SINGLE, MULTIPLE, NUMERIC, REAL and FREQUENCY. subtype is ignored for TARGET_VAR and TOTAL. TARGET_VAR takes id (saved target) or filterTgl (TGL expression). A blank id or filterTgl counts as absent; if both are sent the TGL is used and id is ignored. A variable that cannot be converted is rejected with 400: AE_ERR_412 when a required subtype, id or filterTgl is missing and AE_ERR_416 for an unsupported combination (subtype TEXT in a VAR or CUSTOM_VAR, CUSTOM_VAR with LOGIC, TOTAL or WEIGHTED, or tgl or hidden: true in a category that is not a CUSTOM_CAT of a CUSTOM_VAR with SINGLE or MULTIPLE). Both errors locate the axis, dimension, variable (id or position), field and, when there is one, the offending value. The API does not check the subtype of a CUSTOM_VAR against the variable's definition and uses the declared one as is: send the subtype the variable actually has. In responses, a TARGET_VAR calculated from a TGL expression includes filterTgl (v1 never returns it), so the variable can be sent back unchanged.

    Possible values: >= 1

  • Array [
  • idstring

    Identifier of the variable: the variable id for VAR and CUSTOM_VAR, the saved target id for TARGET_VAR. Not used for TOTAL.

    labelstring

    Label of the variable, in the language of the user. Always returned in responses.

    typeVariableKind (string)

    Kind of variable of a VARIABLES axis. Values are case-sensitive.

    Enum ValueDescription
    VARSurvey variable.
    CUSTOM_VARUser variable saved in the workspace.
    TARGET_VARTarget, a saved one by id or a TGL expression in filterTgl, used as a variable.
    TOTALTotal, with no variable behind it.

    Possible values: [VAR, CUSTOM_VAR, TARGET_VAR, TOTAL]

    subtypeVariableSubtype (string)

    How the variable is measured. Required for VAR and CUSTOM_VAR; ignored for TARGET_VAR and TOTAL. An unknown value returns 400 AE_ERR_401.

    Enum ValueDescription
    SINGLECategorical variable with one answer per respondent.
    MULTIPLECategorical variable with several answers per respondent.
    NUMERICNumeric variable with integer values.
    REALNumeric variable with decimal values.
    FREQUENCYFrequency variable.
    LOGICLogical variable, true or false.
    WEIGHTEDWeighted numeric variable.
    TOTALTotal, with no variable behind it.
    TEXTFree text. Surveys return it, but it cannot be tabulated: sending it returns AE_ERR_416.

    Possible values: [SINGLE, MULTIPLE, NUMERIC, REAL, FREQUENCY, LOGIC, WEIGHTED, TOTAL, TEXT]

    categories object[]

    Categories to calculate, for a categorical variable. Omit it to use all of them.

  • Array [
  • idstring

    Code of the category within its variable. For a JOINT, an id chosen by the caller for the joint. Responses return the base category with id BASE.

    idsstring[]

    Member category ids of a JOINT category. When omitted, the joint contains only id. Ignored for the other types.

    labelstring

    Category label, in the language of the user. Required when the variable is in a split axis (split: true), because split categories are matched by label. Always returned in responses.

    typeCategoryKind (string)required

    Kind of category of a variable. Values are case-sensitive, except JOINT.

    Enum ValueDescription
    CATEGORYA category of a survey variable.
    CUSTOM_CATA category of a user variable.
    JOINTThe union of the categories listed in ids.
    BASEThe base category: responses return it with the id BASE.

    Possible values: [CATEGORY, CUSTOM_CAT, JOINT, BASE]

    selectedboolean

    Marks the category that fixes the slice when its variable is in a PLANES axis. In PLANES, several categories can be selected (one matrix each); in any other axis, more than one returns 400 AE_ERR_404.

    tglstring

    TGL condition of a CUSTOM_CAT category of a user variable (CUSTOM_VAR, subtype SINGLE or MULTIPLE). GET /api/v2/workspace/{workspaceId}/element/{elementId} returns it with resolve=TGL. Send it back unchanged: when every CUSTOM_CAT category of the variable has one, the calculation uses them and does not look the variable up by id. A tgl anywhere else returns 400 AE_ERR_416.

    hiddenboolean

    Marks a CUSTOM_CAT category that is not shown as a row or column but is needed by a JOINT of the same variable. Returned only as true and only with tgl (see resolve in GET /api/v2/workspace/{workspaceId}/element/{elementId}). Send it back unchanged. Accepted only on a CUSTOM_CAT category of a CUSTOM_VAR with subtype SINGLE or MULTIPLE; anywhere else true returns 400 AE_ERR_416.

  • ]
  • filterTglstring

    TGL expression of a TARGET_VAR defined inline. Responses return it for a target calculated from an expression, so the variable can be sent back unchanged.

    selectedboolean

    Whether this variable is the selected one in its axis. Used to pick the slice in the PLANES dimension. Only one variable per axis can be marked as selected outside PLANES; sending more than one in such an axis results in a 400 Bad Request.

  • ]
  • splitboolean

    Whether the axis is split. When true, a CATEGORIES axis that references this axis through parentId must be present, normally in the opposite dimension (the API does not check it): its categories split every variable of this axis. Omitted when false.

  • ]
  • ]
  • matrixList object[]

    One matrix per calculated plane item. Identify each one by its items, never by its position.

  • Array [
  • items object[]

    Plane coordinates of this matrix: for each PLANES axis, the axis id and the item selected in it. Use them to match each matrix with its plane, never its position.

  • Array [
  • axisstring

    Axis the selected item belongs to: its id in Matrix.items (the id of the axis in dimensions), and its label in the combinations of a saved tabulation.

    variable object

    Item selected in the axis. Despite its name it can be any axis item: a statistic (type VARIABLES, REACH or MEDIA), a variable (type VAR, CUSTOM_VAR, TARGET_VAR or TOTAL) with its selected category in items, or another axis item.

    idstring

    Identifier of the item: a statistic id, a variable id, a category id or a carrier id (the id of the carrier in its axis).

    labelstring

    Display label, in the language of the user.

    type object

    Kind of item. A statistic: its family, StatisticFamily (VARIABLES, REACH or MEDIA). A variable: its type, VariableKind (VAR, CUSTOM_VAR, TARGET_VAR or TOTAL); inside its items, the type of each category, CategoryKind. Omitted for a carrier, and for a kind the API does not describe.

    oneOf
    string

    Family of a statistic: the kind of calculation it belongs to. It is the type of a statistic selected in Matrix.items. Values are case-sensitive.

    Enum ValueDescription
    VARIABLESStatistic calculated over survey variables, such as the weighted total.
    REACHReach statistic of a consumption-diary survey.
    MEDIAMedia planning statistic, such as GRP or cover.

    Possible values: [VARIABLES, REACH, MEDIA]

    subtypestring

    For a variable, how it is measured: a VariableSubtype such as SINGLE, MULTIPLE, NUMERIC, REAL, LOGIC, TEXT or FREQUENCY; it can be absent. Absent on statistics, carriers and categories.

    items object[]

    Categories of a variable: the ones selected in the slice. Absent on the rest of the items.

  • Array [
  • 0
    1
    2
    3
    4
    5
    6
    7
    8
    9
  • ]
  • filterTglstring

    Not returned by the v2 endpoints.

    selectedboolean

    In Matrix.items, whether the item is the selected one in its axis. Not returned by tree listings.

  • ]
  • rowCountinteger<int32>

    Number of rows of table.

    columnCountinteger<int32>

    Number of values in each row of table.

    tablearray[]

    Cell values, row by row: table[row][column], following the order of the items of the ROWS and COLUMNS dimensions. With dataType NUMBER (the default) a cell is a number, with STRING its formatted text and with FORMATTED_CELL an object { "value", "formatted" }. A cell of a saved tabulation is always an object { "value", "formatted" }: read value for the number. A cell that cannot be calculated is returned as the string "NaN" when dataType is NUMBER, not as null.

  • ]
  • combinationsinteger<int32>

    Only in GET .../tabulation/{elementId}: number of slices of the saved tabulation.

    indexCombinationinteger<int32>

    Only in GET .../tabulation/{elementId}: position of the returned slice in the list of GET .../tabulation/{elementId}/combinations, starting at 1. It is reliable only when sliceId is passed: without it, it always reports the first slice.

    selfTableLinkstring

    Only in GET .../tabulation/{elementId}: reference to the current slice. Its last path segment is the sliceId; do not call it as it is.

    nextTableLinkstring

    Only in GET .../tabulation/{elementId}: reference to the next slice, as selfTableLink. Omitted on the last slice.

    previousTableLinkstring

    Only in GET .../tabulation/{elementId}: reference to the previous slice, as selfTableLink. Omitted on the first slice.

    diagnostics object

    Issues found by the calculation engine. The table is still returned. Present only when the calculation has something to report.

    levelDiagnosticLevel (string)

    Overall severity of the diagnostics: the worst level among the one of the calculation and the level of each item of diagnostics, so it is never lower than the level of any of them. Each diagnostic keeps its own level; decide what to do from its code.

    Enum ValueDescription
    NONENothing to report.
    INFOInformative message only.
    WARNINGSome items could not be resolved; the rest is calculated.
    ERRORAn error found during the calculation; the table is still returned.

    Possible values: [NONE, INFO, WARNING, ERROR]

    diagnostics object[]

    The diagnostics of this calculation, one per issue found.

  • Array [
  • codestring

    Code of the diagnostic. Base your handling on it, not on the message.

    levelDiagnosticLevel (string)

    Severity of this diagnostic.

    Enum ValueDescription
    NONENothing to report.
    INFOInformative message only.
    WARNINGSome items could not be resolved; the rest is calculated.
    ERRORAn error found during the calculation; the table is still returned.

    Possible values: [NONE, INFO, WARNING, ERROR]

    messageTypeTableKind (string)

    Type of table the message refers to. It gives meaning to the keys of message. Omitted when the table is of a kind this version of the API does not describe.

    Enum ValueDescription
    TABULATIONCross-tabulation of survey variables.
    TRENDEvolution of the figures across survey waves.
    BREAKDOWN_CARRIERSAudience breakdown by carrier.
    DUPLICATIONSDuplication between carriers.
    REACH_TABLEReach and time statistics of the carriers of a diary survey.
    REACH_DUPLICATIONAudience overlap between the carriers of a diary survey.
    REACH_TRENDReach and time statistics compared across survey waves.
    RANKINGRanking of carriers.
    EVALUATIONEvaluation of a media plan.

    Possible values: [TABULATION, TREND, BREAKDOWN_CARRIERS, DUPLICATIONS, REACH_TABLE, REACH_DUPLICATION, REACH_TREND, RANKING, EVALUATION]

    message object

    Details of the diagnostic. Its keys depend on messageType; for example title, type, dimension, axis, status, source and sourceIndex. The values are localized: do not parse them.

    property name*any

    Details of the diagnostic. Its keys depend on messageType; for example title, type, dimension, axis, status, source and sourceIndex. The values are localized: do not parse them.

  • ]
  • Table
    {
    "dimensions": [
    {
    "id": "ROWS",
    "axis": [
    {
    "id": "string",
    "label": "string",
    "axisType": "VARIABLES"
    }
    ]
    }
    ],
    "matrixList": [
    {
    "items": [
    {
    "axis": "string",
    "variable": {
    "id": "string",
    "label": "string",
    "type": "VARIABLES",
    "subtype": "string",
    "items": [
    {}
    ],
    "filterTgl": "string",
    "selected": true
    }
    }
    ],
    "rowCount": 0,
    "columnCount": 0,
    "table": [
    null
    ]
    }
    ],
    "combinations": 0,
    "indexCombination": 0,
    "selfTableLink": "string",
    "nextTableLink": "string",
    "previousTableLink": "string",
    "diagnostics": {
    "level": "NONE",
    "diagnostics": [
    {
    "code": "string",
    "level": "NONE",
    "messageType": "TABULATION",
    "message": {}
    }
    ]
    }
    }