Skip to main content

CategoriesAxis

CATEGORIES axis: the categories of a split VARIABLES axis, which it references through parentId. Its SPLIT categories are matched by label against the categories of the variables of that axis. Place it in the dimension opposite to its parent; the API does not check it. 400 errors: AE_ERR_414 when parentId does not point to a split VARIABLES axis of the request; AE_ERR_412 when parentId, categories or the type of a category is missing.

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.

    parentIdstringrequired

    id of the split VARIABLES axis this axis hangs from. Required.

    Possible values: Value must match regular expression \S

    categories object[]required

    Categories of the split, in order. Required and non-empty.

    Possible values: >= 1

  • Array [
  • typeSplitCategoryKind (string)

    Kind of category. Required: a blank value returns 400 AE_ERR_412 and an unknown one 400 AE_ERR_401.

    Enum ValueDescription
    SPLITA category of the split, matched by label against the categories of the parent variables.
    BASEThe base category of the split.
    TOTALThe total category of the split.

    Possible values: [SPLIT, BASE, TOTAL]

    labelstring

    Category label, in the language of the user. Used by SPLIT categories: it is matched against the labels of the categories of the parent axis variables.

    hiddenboolean

    Whether the category is hidden in the result. Omitted when false.

  • ]
  • CategoriesAxis
    {
    "parentId": "string",
    "categories": [
    {
    "type": "SPLIT",
    "label": "string",
    "hidden": true
    }
    ],
    "id": "string",
    "label": "string",
    "axisType": "VARIABLES"
    }