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.
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.
Identifier of the axis. It is an opaque string: do not read the kind of axis from it, use axisType.
Label of the axis, when it has one.
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 Value | Description |
|---|---|
| VARIABLES | Survey variables, user variables or targets. |
| CATEGORIES | Categories of a split VARIABLES axis. |
| STATISTICS | Statistics to calculate. |
| CARRIERS | Media carriers. |
| SOURCES | Survey waves compared in a TREND table. |
| DIFFERENCES | Difference statistics of a TREND table. |
| CUSTOM_DIARY_EDGE | Values of a diary edge (Reach tables). |
| TIME_DIARY_EDGE | Time ranges of the time edge (Reach tables). |
| MEDIA | Carriers with their insertions. Responses only. |
| MEDIA_PLANS | Media 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.
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.
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.
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 Value | Description |
|---|---|
| CARRIER | One carrier (a media vehicle). It is the default when type is omitted. |
| FOLDER | Every carrier of a folder of the carriers tree. It is read in targetMedia; a CARRIERS axis reads it as a single carrier. |
| CARRIER_JOINT | A joint of the carriers listed in ids, with an id chosen by the caller; in targetMedia it counts as its members. |
| TOTAL_MEDIA | The aggregate of all the media of the survey. It is sent only in a CARRIERS axis, and its id is ignored. |
| TOTAL | The total of the carriers of a table. Responses only. |
| MEDIA_PLAN | One plan of the table. Responses only. |
| MEDIA_PLAN_TOTAL | The total of the plans of the table. Responses only. |
Possible values: [CARRIER, FOLDER, CARRIER_JOINT, TOTAL_MEDIA, TOTAL, MEDIA_PLAN, MEDIA_PLAN_TOTAL]
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.
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.
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.
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.
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 Value | Description |
|---|---|
| CARRIER | One carrier (a media vehicle). It is the default when type is omitted. |
| FOLDER | Every carrier of a folder of the carriers tree. It is read in targetMedia; a CARRIERS axis reads it as a single carrier. |
| CARRIER_JOINT | A joint of the carriers listed in ids, with an id chosen by the caller; in targetMedia it counts as its members. |
| TOTAL_MEDIA | The aggregate of all the media of the survey. It is sent only in a CARRIERS axis, and its id is ignored. |
| TOTAL | The total of the carriers of a table. Responses only. |
| MEDIA_PLAN | One plan of the table. Responses only. |
| MEDIA_PLAN_TOTAL | The total of the plans of the table. Responses only. |
Possible values: [CARRIER, FOLDER, CARRIER_JOINT, TOTAL_MEDIA, TOTAL, MEDIA_PLAN, MEDIA_PLAN_TOTAL]
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.
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.
Identifier of the statistic, as returned by GET /api/v2/statistics. Send it in a STATISTICS axis.
Display label, in the language of the user.
Explanation of what the statistic measures, in the language of the user.
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.
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.
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).
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.
- StatisticFamily
- VariableKind
- CategoryKind
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 Value | Description |
|---|---|
| VARIABLES | Statistic calculated over survey variables, such as the weighted total. |
| REACH | Reach statistic of a consumption-diary survey. |
| MEDIA | Media planning statistic, such as GRP or cover. |
Possible values: [VARIABLES, REACH, MEDIA]
Kind of variable of a VARIABLES axis. Values are case-sensitive.
| Enum Value | Description |
|---|---|
| VAR | Survey variable. |
| CUSTOM_VAR | User variable saved in the workspace. |
| TARGET_VAR | Target, a saved one by id or a TGL expression in filterTgl, used as a variable. |
| TOTAL | Total, with no variable behind it. |
Possible values: [VAR, CUSTOM_VAR, TARGET_VAR, TOTAL]
Kind of category of a variable. Values are case-sensitive, except JOINT.
| Enum Value | Description |
|---|---|
| CATEGORY | A category of a survey variable. |
| CUSTOM_CAT | A category of a user variable. |
| JOINT | The union of the categories listed in ids. |
| BASE | The base category: responses return it with the id BASE. |
Possible values: [CATEGORY, CUSTOM_CAT, JOINT, BASE]
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.
Not returned by the v2 endpoints.
In Matrix.items, whether the item is the selected one in its axis. Not returned by tree listings.
Number of rows of table.
Number of values in each row of table.
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.
{
"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
]
}
}