Skip to main content

RankingTable

Result of a ranking or an evaluation: two dimensions (ROWS and COLUMNS) and a single matrix. Unlike the tables returned by POST /api/v2/table/{surveyCode}, it has matrix and not matrixList.

dimensions object[]

ROWS and COLUMNS, in that order.

  • Array [
  • idstring

    Which dimension it is: ROWS or COLUMNS.

    Possible values: [ROWS, COLUMNS]

    axis object[]

    The axes of the dimension. A ranking or an evaluation has one axis per dimension.

  • Array [
  • idstring

    Identifier of the axis. It is an opaque string: do not read the kind of axis from it, use axisType.

    labelstring

    Label of the axis, when it has one.

    axisTypeAxisKind (string)

    Kind of axis: CARRIERS for the rows of a ranking, MEDIA for the rows of an evaluation and STATISTICS for the columns of both.

    Enum ValueDescription
    VARIABLESSurvey variables, user variables or targets.
    CATEGORIESCategories of a split VARIABLES axis.
    STATISTICSStatistics to calculate.
    CARRIERSMedia carriers.
    SOURCESSurvey waves compared in a TREND table.
    DIFFERENCESDifference statistics of a TREND table.
    CUSTOM_DIARY_EDGEValues of a diary edge (Reach tables).
    TIME_DIARY_EDGETime ranges of the time edge (Reach tables).
    MEDIACarriers with their insertions. Responses only.
    MEDIA_PLANSMedia plans. Responses only.

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

    carriers object[]

    Rows of a ranking, in order. With hierarchy, folder rows (type FOLDER) appear above their carriers.

  • Array [
  • idstring

    Identifier of the carrier or folder, as returned by the carriers tree. For a CARRIER_JOINT, an id chosen by the caller for the joint, echoed in the response. Ignored for TOTAL_MEDIA.

    labelstring

    Display label, in the language of the user. Optional in requests; for TOTAL_MEDIA it sets the label of the aggregate. Always returned in responses.

    typeCarrierType (string)

    Kind of carrier. In requests: CARRIER (the default when omitted) is one carrier; FOLDER is every carrier of a folder (targetMedia only); CARRIER_JOINT is a joint of the carriers listed in ids; TOTAL_MEDIA is the aggregate of all media (CARRIERS axis only). The meaning depends on the context: in a CARRIERS axis any value other than CARRIER_JOINT and TOTAL_MEDIA is a single carrier; targetMedia reads FOLDER as a folder and flattens a joint into its members, and any other value is a single carrier. Responses can also return TOTAL, MEDIA_PLAN and MEDIA_PLAN_TOTAL; the field is omitted for a kind the API does not describe.

    Enum ValueDescription
    CARRIEROne carrier (a media vehicle). It is the default when type is omitted.
    FOLDEREvery carrier of a folder of the carriers tree. It is read in targetMedia; a CARRIERS axis reads it as a single carrier.
    CARRIER_JOINTA joint of the carriers listed in ids, with an id chosen by the caller; in targetMedia it counts as its members.
    TOTAL_MEDIAThe aggregate of all the media of the survey. It is sent only in a CARRIERS axis, and its id is ignored.
    TOTALThe total of the carriers of a table. Responses only.
    MEDIA_PLANOne plan of the table. Responses only.
    MEDIA_PLAN_TOTALThe total of the plans of the table. Responses only.

    Possible values: [CARRIER, FOLDER, CARRIER_JOINT, TOTAL_MEDIA, TOTAL, MEDIA_PLAN, MEDIA_PLAN_TOTAL]

    idsstring[]

    Member carrier ids of a CARRIER_JOINT: at least 2, plus a caller-assigned id for the joint, which is echoed back in the response. Ignored for the other types.

    insertionsinteger<int32>[]

    Insertions of the carrier in a calculated study table (a MEDIA axis): a single value, the insertions of that row in its plan. Ignored in requests.

  • ]
  • mediaItems object[]

    Rows of an evaluation, in order, grouped by plan: a plan row (type MEDIA_PLAN) followed by the rows of its carriers. The plan row holds the figures of the plan as a whole: there is no separate total row. insertions holds a single value: the insertions of that plan, or of that carrier in that plan.

  • Array [
  • idstring

    Identifier of the carrier or folder, as returned by the carriers tree. For a CARRIER_JOINT, an id chosen by the caller for the joint, echoed in the response. Ignored for TOTAL_MEDIA.

    labelstring

    Display label, in the language of the user. Optional in requests; for TOTAL_MEDIA it sets the label of the aggregate. Always returned in responses.

    typeCarrierType (string)

    Kind of carrier. In requests: CARRIER (the default when omitted) is one carrier; FOLDER is every carrier of a folder (targetMedia only); CARRIER_JOINT is a joint of the carriers listed in ids; TOTAL_MEDIA is the aggregate of all media (CARRIERS axis only). The meaning depends on the context: in a CARRIERS axis any value other than CARRIER_JOINT and TOTAL_MEDIA is a single carrier; targetMedia reads FOLDER as a folder and flattens a joint into its members, and any other value is a single carrier. Responses can also return TOTAL, MEDIA_PLAN and MEDIA_PLAN_TOTAL; the field is omitted for a kind the API does not describe.

    Enum ValueDescription
    CARRIEROne carrier (a media vehicle). It is the default when type is omitted.
    FOLDEREvery carrier of a folder of the carriers tree. It is read in targetMedia; a CARRIERS axis reads it as a single carrier.
    CARRIER_JOINTA joint of the carriers listed in ids, with an id chosen by the caller; in targetMedia it counts as its members.
    TOTAL_MEDIAThe aggregate of all the media of the survey. It is sent only in a CARRIERS axis, and its id is ignored.
    TOTALThe total of the carriers of a table. Responses only.
    MEDIA_PLANOne plan of the table. Responses only.
    MEDIA_PLAN_TOTALThe total of the plans of the table. Responses only.

    Possible values: [CARRIER, FOLDER, CARRIER_JOINT, TOTAL_MEDIA, TOTAL, MEDIA_PLAN, MEDIA_PLAN_TOTAL]

    idsstring[]

    Member carrier ids of a CARRIER_JOINT: at least 2, plus a caller-assigned id for the joint, which is echoed back in the response. Ignored for the other types.

    insertionsinteger<int32>[]

    Insertions of the carrier in a calculated study table (a MEDIA axis): a single value, the insertions of that row in its plan. Ignored in requests.

  • ]
  • statistics object[]

    Columns, in order: the statistics of the result.

  • Array [
  • idstring

    Identifier of the statistic, as returned by GET /api/v2/statistics. Send it in a STATISTICS axis.

    labelstring

    Display label, in the language of the user.

    descriptionstring

    Explanation of what the statistic measures, in the language of the user.

    selectedboolean

    Not returned by GET /api/v2/statistics. In table requests and responses it marks the selected statistic of an axis; in a PLANES axis several can be selected (one matrix each), in any other axis at most one.

  • ]
  • ]
  • ]
  • matrix object

    The only matrix of the result. table[r][c] is the value of row r and column c: rows follow the row axis (carriers in a ranking, mediaItems in an evaluation) and columns follow the statistics of the COLUMNS axis.

    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.

    RankingTable
    {
    "dimensions": [
    {
    "id": "ROWS",
    "axis": [
    {
    "id": "string",
    "label": "string",
    "axisType": "VARIABLES",
    "carriers": [
    {
    "id": "string",
    "label": "string",
    "type": "CARRIER",
    "ids": [
    "string"
    ],
    "insertions": [
    0
    ]
    }
    ],
    "mediaItems": [
    {
    "id": "string",
    "label": "string",
    "type": "CARRIER",
    "ids": [
    "string"
    ],
    "insertions": [
    0
    ]
    }
    ],
    "statistics": [
    {
    "id": "string",
    "label": "string",
    "description": "string",
    "selected": true
    }
    ]
    }
    ]
    }
    ],
    "matrix": {
    "items": [
    {
    "axis": "string",
    "variable": {
    "id": "string",
    "label": "string",
    "type": "VARIABLES",
    "subtype": "string",
    "items": [
    {}
    ],
    "filterTgl": "string",
    "selected": true
    }
    }
    ],
    "rowCount": 0,
    "columnCount": 0,
    "table": [
    null
    ]
    }
    }