Skip to main content

Building tables

A table is the central object of the TOM External API: you describe the dimensions, axes, variables and statistics you want, and the API calculates the figures. This guide explains how to build the request, how to read the response and how to reuse tables saved in a workspace.

If you have not calculated a table yet, start with Getting started.

1. Choosing the operation​

You want toUse
Calculate a table from a definitionPOST /api/v2/table/{surveyCode}
Get the same table rendered as HTMLPOST /api/v2/table/{surveyCode}/html (same body)
Calculate a Reach table (REACH_TABLE, REACH_DUPLICATION or REACH_TREND)POST /api/v2/reach/{surveyCode}, or POST /api/v2/table/{surveyCode} with the same body, targetMedia and diaryFilters included (see Reach)
Read a tabulation saved in a workspace, as it isGET /api/v2/workspace/{workspaceId}/survey/{surveyCode}/tabulation/{elementId}
Recalculate a saved tabulation with changesGET /api/v2/workspace/{workspaceId}/element/{elementId}, edit the table it returns, then POST /api/v2/table/{surveyCode}
Compare carriers or media plansRanking, evaluation and response curve (see Media planning)

Nothing you send to the calculation operations is stored.

2. Anatomy of the request​

{
"tableType": "TABULATION",
"dimensions": [ ... ],
"target": { "filterTgl": "EDA1.D3" },
"dataType": "FORMATTED_CELL",
"locale": "en-GB",
"decimals": 1
}
FieldMeaning
tableTypeThe kind of table. TABULATION by default. See section 7.
dimensionsUp to three dimensions, ROWS, COLUMNS and PLANES, in upper case. Required.
targetAn audience that filters the whole table: a saved target id or a TGL expression in filterTgl. If you send both, filterTgl is used.
dataTypeHow cells are returned: NUMBER (default), STRING or FORMATTED_CELL. Section 9.
locale, decimalsThe regional number format and the number of decimals of the formatted values. They do not change the raw numbers or the language of the labels.
extraParamsAdvanced switches. showBases (boolean) adds the base categories, and trendCategoriesMode chooses the categories of a trend (section 8.3). Other keys are reserved.
weeks, weightThe weeks and the weighting of a TABULATION or REACH_TABLE. Section 8.7.
targetMedia, diaryFiltersThe Reach settings, only with a Reach tableType. See Reach.

Unknown fields at the top level, in weight, in dimensions, in axes, in split categories, in the survey waves of a SOURCES axis and in their weight are rejected with 400 AE_ERR_411. Unknown fields inside variables, categories, statistics, target and targetBase are ignored, so check their spelling (for example, categories, not items).

3. Axes​

Each dimension holds one or more axes. The axisType of an axis selects its kind and the fields it accepts:

axisTypeHoldsTypical use
VARIABLESvariables: survey variables (VAR), user variables (CUSTOM_VAR), targets (TARGET_VAR) and totals (TOTAL)Rows, columns or planes
STATISTICSstatistics to calculatePLANES or COLUMNS
CATEGORIEScategories of a split VARIABLES axis, which it references with parentIdSplit tables (section 6)
SOURCES, DIFFERENCESSurvey waves to compare, and difference statistics between themTREND and REACH_TREND tables
CARRIERScarriers: media carriers (CARRIER), joints of carriers (CARRIER_JOINT) and the total of all media (TOTAL_MEDIA)BREAKDOWN_CARRIERS, DUPLICATIONS and Reach tables
CUSTOM_DIARY_EDGE, TIME_DIARY_EDGEDiary edgesReach tables

The id of an axis is optional. When you omit it, the API assigns the lowest unused positive integer. Give each axis a unique id when another axis or your own code refers to it. Every axis can also carry a label.

MEDIA and MEDIA_PLANS axes appear only in responses; sending them is rejected with AE_ERR_410. A request needs at least one dimension with at least one axis (AE_ERR_413), and a STATISTICS axis is required.

An axis that misses a required value (the list of the axis, parentId...) is rejected with AE_ERR_412. An axis with no axisType, or with an unknown one, is rejected with AE_ERR_409.

4. Variables in a VARIABLES axis​

Each entry of variables has a type:

typeWhat it isWhat you send
VARA survey variableid (the variable code) and subtype
CUSTOM_VARA user variable of a workspaceid (from GET .../user-vars) and subtype
TARGET_VARA target used as a row, column or planeid of a saved target, or filterTgl with a TGL expression, and optionally label
TOTALThe total of the dimensionOnly { "type": "TOTAL" }

The rules the API applies:

  • A VAR or CUSTOM_VAR needs subtype: send the one the variable actually has (see the variables list). A missing one is AE_ERR_412.
  • TEXT variables cannot be tabulated, and a CUSTOM_VAR cannot have the subtype LOGIC, TOTAL or WEIGHTED (AE_ERR_416).
  • A TARGET_VAR needs id or filterTgl. With neither, it is AE_ERR_412; with both, filterTgl is used and id is ignored.
  • For a categorical variable, omit categories to use all of them, or list the ones you want: { "id": "D1", "type": "CATEGORY" } for a category of the variable, or { "id": "Y14_24", "type": "JOINT", "label": "14 to 24", "ids": ["D1", "D2"] } to merge several categories into one. A category the variable does not have, or a JOINT without ids, is VA_ERR_102.
  • A CUSTOM_VAR that cannot be resolved, for example an id that is not a user variable, is CV_ERR_109. In a TREND, it is a WARNING diagnostic of each survey wave instead.
  • A table needs at least one variable other than TOTAL: a table with only a TOTAL variable, or with only a STATISTICS axis, is TB_ERR_104.
  • A selected flag picks items (section 5).

5. Selection and planes​

A table has up to three dimensions, and the third, PLANES, works as a stack of slices:

  • Each combination of one selected item per PLANES axis is a slice, and the response has one matrix per slice.
  • When no item of a PLANES axis is selected, the first valid one is used.
  • When several items of one PLANES axis are selected, the response has one matrix per selected item. To select several categories of a plane variable, mark the variable itself as selected too.
  • Outside PLANES, an axis can have at most one selected item. More than one is AE_ERR_404.
  • A SOURCES axis has the opposite rule: at most one selected survey wave in PLANES, and any number in ROWS or COLUMNS (section 8.3).

This request selects two statistics in PLANES, so the response has two matrices:

{
"dimensions": [
{
"id": "ROWS",
"axis": [
{ "axisType": "VARIABLES", "variables": [{ "id": "SEX", "type": "VAR", "subtype": "SINGLE" }] }
]
},
{
"id": "COLUMNS",
"axis": [
{ "axisType": "VARIABLES", "variables": [{ "id": "EDA1", "type": "VAR", "subtype": "SINGLE" }] }
]
},
{
"id": "PLANES",
"axis": [
{
"id": "STATISTICS",
"axisType": "STATISTICS",
"statistics": [{ "id": "wTotal", "selected": true }, { "id": "ColPercentWeighted", "selected": true }]
}
]
}
]
}

6. Split axes​

A split axis lays the categories of a variable along the opposite dimension. It is expressed as two linked axes: a VARIABLES axis with "split": true, and a CATEGORIES axis in the opposite dimension whose parentId is the id of the first.

{ "axisType": "VARIABLES", "id": "1", "label": "Axis 1", "split": true, "variables": [ ... ] }

{ "axisType": "CATEGORIES", "id": "2", "label": "* Axis 1", "parentId": "1",
"categories": [ { "type": "TOTAL" }, { "type": "BASE" },
{ "type": "SPLIT", "label": "Male" }, { "type": "SPLIT", "label": "Female" } ] }
  • type accepts SPLIT, BASE and TOTAL. label is meaningful only for SPLIT.
  • During calculation, SPLIT categories are matched by label against the categories of the variables of the parent axis. The server does not derive categories: if you change the variables of the parent axis, recompute the labels.
  • A CATEGORIES axis whose parentId is missing from the request, or does not point to a VARIABLES axis with "split": true, is rejected with AE_ERR_414.
  • A tabulation saved in a workspace emits both axes, so you can read it and send it again unchanged.

7. Table types​

tableTypeWhat it calculatesModule
TABULATIONA cross-tabulation of survey variables (the default)Tabulation
TRENDThe evolution of a crossing across survey waves, with SOURCES and DIFFERENCES axes (section 8.3)Study
BREAKDOWN_CARRIERSThe audience broken down by carrier, with a CARRIERS axisStudy
DUPLICATIONSThe audience duplication between carriersStudy
REACH_TABLE, REACH_DUPLICATION, REACH_TRENDReach tables on consumption-diary surveys; REACH_TREND compares them across survey waves (see Reach)Reach

Statistics depend on the table type: list them with GET /api/v2/statistics?tableType=... (for the two statistics axes of a TREND, see section 8.3), or, for Reach, with reach-capabilities. An invalid statistic gives 400 (T_ERR_106). A REACH_TREND checks its statistics before calculating: an id outside the catalog of its axis gives 400 (AE_ERR_402). The ids of each table type are fixed: an id that exists keeps its name and its meaning, and new ones can be added, so do not fail on an id you do not know. A label or description that looks like a name between question marks (for example ?KEY?) has no translation for the language of the user yet: use the id.

8. Recipes​

8.1. Filter the whole table by an audience​

Add target to the request, with a saved target or an inline expression:

{ "target": { "id": "4B81EAA3CCF416C9E063CD6710AC823E" } }
{ "target": { "filterTgl": "SEX.D1 AND EDA1.D3" } }

8.2. Use targets as columns​

Put TARGET_VAR variables in a VARIABLES axis. One column per audience:

{
"axisType": "VARIABLES",
"variables": [
{ "type": "TARGET_VAR", "id": "4B81EAA3CCF416C9E063CD6710AC823E" },
{ "type": "TARGET_VAR", "label": "Women", "filterTgl": "SEX.D2" }
]
}

8.3. Trend across survey waves​

tableType: TREND with a VARIABLES axis in the rows, a DIFFERENCES axis in the columns, and a STATISTICS axis and a SOURCES axis in the planes:

{
"tableType": "TREND",
"dimensions": [
{
"id": "ROWS",
"axis": [
{
"id": "variables",
"axisType": "VARIABLES",
"variables": [
{
"id": "SEX",
"type": "VAR",
"subtype": "SINGLE",
"selected": true,
"categories": [{ "id": "D1", "type": "CATEGORY", "selected": true }]
}
]
}
]
},
{
"id": "COLUMNS",
"axis": [
{ "id": "differences", "axisType": "DIFFERENCES", "differences": [{ "id": "TrendTotal", "selected": true }] }
]
},
{
"id": "PLANES",
"axis": [
{ "id": "statistics", "axisType": "STATISTICS", "statistics": [{ "id": "wTotal", "selected": true }] },
{
"id": "sources",
"axisType": "SOURCES",
"sources": [
{ "id": "APP_DEMO_2024", "label": "APP_DEMO_2024" },
{ "id": "APP_DEMO_2025", "label": "APP_DEMO_2025" }
]
}
]
}
]
}

Each item of sources is a survey wave:

FieldUse
idThe code of the survey, from GET /api/v2/users/surveys.
labelThe name to show. Ignored when sent; returned in responses.
selectedThe wave shown when the SOURCES axis is in PLANES.
weeksThe weeks of the wave, with the ids of GET /api/v2/survey/{surveyCode}/weeks-and-weights (section 8.7).
weightThe weighting of the wave: an item of weights of the same operation. Only its id is read, and it is required.
  • A survey wave is strict: an unknown field in it or in its weight is AE_ERR_411, and a weight without id is AE_ERR_412. An empty weeks is the same as not sending it, and a week sent twice is AE_ERR_400.
  • The API does not check the weeks and the weighting of a wave: the calculation engine does. A wave that the user cannot use, a wave of a survey with weeks that sends none or one the survey does not have, and a wave with a weighting its survey does not have are left out with a TR_ERR_107 diagnostic of level WARNING. The other waves are calculated and the answer is 200. With no valid wave left, the answer is 400 TR_ERR_105.
  • A survey without weeks ignores weeks, and a survey without weightings ignores weight. A wave without weight gets no weighting from the API.
  • In PLANES, at most one wave can be selected: more is AE_ERR_404, and without any the first wave is shown. In ROWS or COLUMNS, any number of waves can be selected, and selected does not change the figures.
  • The DIFFERENCES axis takes the ids of GET /api/v2/statistics?tableType=TREND. The STATISTICS axis of a trend takes the ids of GET /api/v2/statistics?tableType=TREND&axis=STATISTICS.
  • A TREND without a SOURCES axis is TR_ERR_101, and without a DIFFERENCES axis, TR_ERR_103.
  • The sources of a response carry selected, weeks and weight when they have a value, so a response can be sent again.

In a weekly survey, each wave takes its weeks and its weighting from the discovery operation. Two waves of the same survey can compare two weeks:

{
"id": "sources",
"axisType": "SOURCES",
"sources": [
{ "id": "WEEKLY_DEMO", "weeks": ["2025/06"], "weight": { "id": "W1" } },
{ "id": "WEEKLY_DEMO", "weeks": ["2025/07"], "weight": { "id": "W1" } }
]
}

extraParams.trendCategoriesMode chooses the categories that enter each wave. The base categories always enter:

ValueCategories that enter
ONLY_ACTIVE_SOURCE_CATEGORIESThe ones valid in the survey of the path. The default.
ALLThe ones valid in at least one wave.
VALID_IN_ALL_SOURCESThe ones valid in every wave.

Any other value is TR_ERR_106. The key has no effect outside a TREND or a REACH_TREND.

A REACH_TREND compares the statistics of a Reach table across survey waves: it needs a SOURCES, a DIFFERENCES and a CARRIERS axis, and without one of them it is AE_ERR_412. Its waves follow the rules above, but their weeks and weighting only decide whether a wave is calculated: they do not change the Reach figures, so two waves of the same survey that differ only in them give identical columns. See Reach.

8.4. Breakdown by carrier​

tableType: BREAKDOWN_CARRIERS with a CARRIERS axis. Take carrier ids from the carriers list, and statistic ids from GET /api/v2/statistics?tableType=BREAKDOWN_CARRIERS:

{
"tableType": "BREAKDOWN_CARRIERS",
"dimensions": [
{
"id": "ROWS",
"axis": [
{
"id": "1",
"axisType": "CARRIERS",
"carriers": [{ "id": "TVCH1005D1F1", "type": "CARRIER" }, { "id": "TVCH1005D1F2", "type": "CARRIER" }]
}
]
},
{ "id": "COLUMNS", "axis": [{ "id": "2", "axisType": "VARIABLES", "variables": [{ "type": "TOTAL" }] }] },
{
"id": "PLANES",
"axis": [{ "id": "3", "axisType": "STATISTICS", "statistics": [{ "id": "CONTACT", "selected": true }] }]
}
]
}

8.5. Formatted cells​

Set dataType to FORMATTED_CELL, and optionally locale and decimals, to get the value and the formatted text of every cell:

{ "dataType": "FORMATTED_CELL", "locale": "en-GB", "decimals": 1 }

8.6. Recalculate a saved tabulation​

  1. Find its id in the tabulations list of GET /api/v2/workspace/{workspaceId}.
  2. Call GET /api/v2/workspace/{workspaceId}/element/{elementId} and take its table field.
  3. Edit it and send it to POST /api/v2/table/{surveyCode}.

The returned table carries the dimensions, the table type, extraParams (trendCategoriesMode included), the saved target and, when the base was saved applied, the targetBase:

  • A target or a base comes with id when it was saved by id, with filterTgl when there is a saved TGL expression or 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 comes with its label only and is listed in notReproducible, outside table. Define it again, by id or with filterTgl: sent unchanged, it is rejected with AE_ERR_405.
  • A TABULATION or REACH_TABLE carries its effective weeks and weight; a TREND or REACH_TREND carries them in each survey wave. A Reach table carries its targetMedia and diaryFilters when they were saved, and can also be sent to POST /api/v2/reach/{surveyCode}.

Send the request to the surveyCode of the element to get the figures of the element. It is the survey currently active in the workspace, not necessarily the survey the element was saved with. See Workspaces, targets and reusable elements for the details. The dimensions of any response can also be posted back to recalculate the same table: PLANES then carries only the slices that were returned.

8.7. Weeks and weighting​

A survey can have weeks (a weekly survey) and several weightings. GET /api/v2/survey/{surveyCode}/weeks-and-weights lists the ones it accepts, in the order of the survey. It needs no application module.

  • weeks: each week has its id (YYYY/WW), year, week, and its first and last day in startDate and endDate.
  • weights: each weighting has its id, its label (the survey's own, not translated), its universe when there is one, and isDefault.
  • Both lists are always present, empty when the survey has none. A survey gains weeks when new data is loaded, so do not keep them for long.

A TABULATION or REACH_TABLE takes them at the top level of the request:

{ "weeks": ["2025/07"], "weight": { "id": "W1" } }
  • An item of weights can be sent as weight as it is returned: only its id is read. A weight without id is AE_ERR_412.
  • They are checked against the survey before calculating. A week or a weighting the survey does not have, or any value in a survey without weeks or weightings, is AE_ERR_400, and the message names the value. An empty weeks is the same as not sending it, and a week sent twice is AE_ERR_400.
  • With several weeks, the weighted figures are the mean of the weeks; Sample and the statistics calculated on the sample come from the latest of them.
  • Without them, the first week of the survey and its default weighting, the one marked isDefault, are used.
  • With any other tableType they are AE_ERR_400: a TREND or REACH_TREND takes them in each survey wave (section 8.3).
  • In a REACH_TABLE they are checked, but they do not change the Reach figures.

9. Reading the response​

The response repeats dimensions with the resolved structure (labels, categories, assigned axis ids) and adds matrixList:

  • matrixList[i].table[r][c] is the value for the r-th item of ROWS and the c-th item of COLUMNS, in the order of dimensions. rowCount and columnCount give the size.
  • Identify each matrix by its items (one entry per PLANES axis, with the axis id and the item of the slice), never by its position.
  • In dimensions, PLANES lists only the selected items.
  • The cell depends on dataType: a number (NUMBER), a formatted text (STRING) or an object { "value", "formatted" } (FORMATTED_CELL). With NUMBER, a cell that cannot be calculated (for example, when the target selects nobody) is the string "NaN", not null.
  • diagnostics appears only when the calculation has something to report, for example a survey wave of a trend that was left out, or a user variable or a saved target of a trend that could not be resolved. Its level is the worst level of its diagnostics. Outside a trend, a user variable that cannot be resolved is an error, not a diagnostic (CV_ERR_109).
  • Labels come in the language of the user.

The HTML operation ignores dataType, locale and decimals. When several items of a PLANES axis are selected, it renders only the first selected item. Send Accept: text/html: a request that does not accept it gets 406 E406.

10. Stored tabulations​

A tabulation saved in a workspace is a data cube. GET .../tabulation/{elementId} returns its structure and one slice per call:

  • Without sliceId, you get the slice saved as current. With sliceId, you get that slice.
  • GET .../tabulation/{elementId}/combinations lists every slice with its sliceId. Call it once, then pass each sliceId explicitly in the query string of the tabulation call. A sliceId is an opaque token: pass it unchanged.
  • combinations is the number of slices. indexCombination is the position of the returned slice, starting at 1; it is reliable only when you pass sliceId.
  • selfTableLink, nextTableLink and previousTableLink reference the current, next and previous slice. Do not call them as they are: their last path segment is a sliceId, which you pass in the sliceId query parameter.
  • matrixList contains exactly one matrix: the returned slice.
  • In a saved tabulation every cell is an object { "value", "formatted" }: read value for the number. formatted is the text shown in the TOM web application, in the locale of the user.

11. Common errors​

Status and errorCodeCause
400 AE_ERR_400An invalid value: a negative decimals, an extraParams switch with an invalid value, a value of the wrong JSON type, weeks or weight with a table type that does not take them or with a value the survey does not have, or targetMedia or diaryFilters with a table type that is not Reach.
400 AE_ERR_401Invalid value of an enumerated field: tableType, dataType, the type or subtype of a variable, or the type of a category.
400 AE_ERR_402In a REACH_TREND, a statistic outside the catalog of its axis.
400 AE_ERR_404More than one selected item or category in an axis outside PLANES, or more than one selected survey wave in a SOURCES axis in PLANES.
400 AE_ERR_405target or targetBase has neither a non-blank id nor a non-blank filterTgl, for example one listed in notReproducible.
400 AE_ERR_409, AE_ERR_410axisType is missing or unknown, the axis type is valid only in responses, a SOURCES or DIFFERENCES axis is in a table that is not a TREND or a REACH_TREND, or the CARRIERS axis of a REACH_TREND is in PLANES.
400 AE_ERR_411A field that the object does not accept, also in weight, in a survey wave or in its weight.
400 AE_ERR_412A required value is missing: the list of an axis, parentId, the subtype, id or filterTgl of a variable, or the id of a weight. Also a REACH_TREND without its SOURCES, DIFFERENCES or CARRIERS axis.
400 AE_ERR_413dimensions is absent or empty, or a dimension has no axes.
400 AE_ERR_414A CATEGORIES axis whose parentId is not a split VARIABLES axis.
400 AE_ERR_416An unsupported variable.
400 T_ERR_104, T_ERR_106, VA_ERR_101No statistics, a statistic that is not valid for the table type, or an unknown variable.
400 VA_ERR_102A category the variable does not have, or a JOINT category without ids.
400 CV_ERR_109A CUSTOM_VAR that cannot be resolved (outside a trend).
400 TB_ERR_104No variable to tabulate: only a TOTAL variable, or only a STATISTICS axis. Also a saved tabulation whose variables are not in the survey.
400 TG_ERR_113target or targetBase has an id that does not identify a saved target.
400 TGL_ERR_101A filterTgl uses a variable or category that does not exist in the survey.
400 TR_ERR_101, TR_ERR_103A TREND without a SOURCES axis, or without a DIFFERENCES axis.
400 TR_ERR_105, TR_ERR_109A trend with no valid survey wave, or with none left after checking the variables of the table.
400 TR_ERR_106trendCategoriesMode is not a valid value.
401 SO_ERR_203The survey is not in your profile or does not exist.
403 AE_ERR_408The user does not have the module that the table type needs: Reach for every Reach type, REACH_TREND included.
422 TGL_INVALIDA filterTgl cannot be parsed, in target, targetBase or a TARGET_VAR.

The full list is in Errors and troubleshooting.