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 to | Use |
|---|---|
| Calculate a table from a definition | POST /api/v2/table/{surveyCode} |
| Get the same table rendered as HTML | POST /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 is | GET /api/v2/workspace/{workspaceId}/survey/{surveyCode}/tabulation/{elementId} |
| Recalculate a saved tabulation with changes | GET /api/v2/workspace/{workspaceId}/element/{elementId}, edit the table it returns, then POST /api/v2/table/{surveyCode} |
| Compare carriers or media plans | Ranking, 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
}
| Field | Meaning |
|---|---|
tableType | The kind of table. TABULATION by default. See section 7. |
dimensions | Up to three dimensions, ROWS, COLUMNS and PLANES, in upper case. Required. |
target | An audience that filters the whole table: a saved target id or a TGL expression in filterTgl. If you send both, filterTgl is used. |
dataType | How cells are returned: NUMBER (default), STRING or FORMATTED_CELL. Section 9. |
locale, decimals | The 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. |
extraParams | Advanced switches. showBases (boolean) adds the base categories, and trendCategoriesMode chooses the categories of a trend (section 8.3). Other keys are reserved. |
weeks, weight | The weeks and the weighting of a TABULATION or REACH_TABLE. Section 8.7. |
targetMedia, diaryFilters | The 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:
axisType | Holds | Typical use |
|---|---|---|
VARIABLES | variables: survey variables (VAR), user variables (CUSTOM_VAR), targets (TARGET_VAR) and totals (TOTAL) | Rows, columns or planes |
STATISTICS | statistics to calculate | PLANES or COLUMNS |
CATEGORIES | categories of a split VARIABLES axis, which it references with parentId | Split tables (section 6) |
SOURCES, DIFFERENCES | Survey waves to compare, and difference statistics between them | TREND and REACH_TREND tables |
CARRIERS | carriers: 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_EDGE | Diary edges | Reach 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:
type | What it is | What you send |
|---|---|---|
VAR | A survey variable | id (the variable code) and subtype |
CUSTOM_VAR | A user variable of a workspace | id (from GET .../user-vars) and subtype |
TARGET_VAR | A target used as a row, column or plane | id of a saved target, or filterTgl with a TGL expression, and optionally label |
TOTAL | The total of the dimension | Only { "type": "TOTAL" } |
The rules the API applies:
- A
VARorCUSTOM_VARneedssubtype: send the one the variable actually has (see the variables list). A missing one isAE_ERR_412. TEXTvariables cannot be tabulated, and aCUSTOM_VARcannot have the subtypeLOGIC,TOTALorWEIGHTED(AE_ERR_416).- A
TARGET_VARneedsidorfilterTgl. With neither, it isAE_ERR_412; with both,filterTglis used andidis ignored. - For a categorical variable, omit
categoriesto 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 aJOINTwithoutids, isVA_ERR_102. - A
CUSTOM_VARthat cannot be resolved, for example anidthat is not a user variable, isCV_ERR_109. In aTREND, it is aWARNINGdiagnostic of each survey wave instead. - A table needs at least one variable other than
TOTAL: a table with only aTOTALvariable, or with only aSTATISTICSaxis, isTB_ERR_104. - A
selectedflag 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
PLANESaxis is a slice, and the response has one matrix per slice. - When no item of a
PLANESaxis is selected, the first valid one is used. - When several items of one
PLANESaxis are selected, the response has one matrix per selected item. To select several categories of a plane variable, mark the variable itself asselectedtoo. - Outside
PLANES, an axis can have at most one selected item. More than one isAE_ERR_404. - A
SOURCESaxis has the opposite rule: at most one selected survey wave inPLANES, and any number inROWSorCOLUMNS(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" } ] }
typeacceptsSPLIT,BASEandTOTAL.labelis meaningful only forSPLIT.- During calculation,
SPLITcategories are matched by label against the categories of the variables of the parent axis. The server does not derivecategories: if you change the variables of the parent axis, recompute the labels. - A
CATEGORIESaxis whoseparentIdis missing from the request, or does not point to aVARIABLESaxis with"split": true, is rejected withAE_ERR_414. - A tabulation saved in a workspace emits both axes, so you can read it and send it again unchanged.
7. Table types
tableType | What it calculates | Module |
|---|---|---|
TABULATION | A cross-tabulation of survey variables (the default) | Tabulation |
TREND | The evolution of a crossing across survey waves, with SOURCES and DIFFERENCES axes (section 8.3) | Study |
BREAKDOWN_CARRIERS | The audience broken down by carrier, with a CARRIERS axis | Study |
DUPLICATIONS | The audience duplication between carriers | Study |
REACH_TABLE, REACH_DUPLICATION, REACH_TREND | Reach 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:
| Field | Use |
|---|---|
id | The code of the survey, from GET /api/v2/users/surveys. |
label | The name to show. Ignored when sent; returned in responses. |
selected | The wave shown when the SOURCES axis is in PLANES. |
weeks | The weeks of the wave, with the ids of GET /api/v2/survey/{surveyCode}/weeks-and-weights (section 8.7). |
weight | The 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
weightisAE_ERR_411, and aweightwithoutidisAE_ERR_412. An emptyweeksis the same as not sending it, and a week sent twice isAE_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_107diagnostic of levelWARNING. The other waves are calculated and the answer is200. With no valid wave left, the answer is400TR_ERR_105. - A survey without weeks ignores
weeks, and a survey without weightings ignoresweight. A wave withoutweightgets no weighting from the API. - In
PLANES, at most one wave can beselected: more isAE_ERR_404, and without any the first wave is shown. InROWSorCOLUMNS, any number of waves can be selected, andselecteddoes not change the figures. - The
DIFFERENCESaxis takes the ids ofGET /api/v2/statistics?tableType=TREND. TheSTATISTICSaxis of a trend takes the ids ofGET /api/v2/statistics?tableType=TREND&axis=STATISTICS. - A
TRENDwithout aSOURCESaxis isTR_ERR_101, and without aDIFFERENCESaxis,TR_ERR_103. - The
sourcesof a response carryselected,weeksandweightwhen 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:
| Value | Categories that enter |
|---|---|
ONLY_ACTIVE_SOURCE_CATEGORIES | The ones valid in the survey of the path. The default. |
ALL | The ones valid in at least one wave. |
VALID_IN_ALL_SOURCES | The 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
- Find its id in the
tabulationslist ofGET /api/v2/workspace/{workspaceId}. - Call
GET /api/v2/workspace/{workspaceId}/element/{elementId}and take itstablefield. - 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
idwhen it was saved by id, withfilterTglwhen there is a saved TGL expression or its saved conditions can be written as one, and withlabelwhen there is one. Withresolve=TGL, a target or a base saved byidalso returns itsfilterTgl. - A target or a base that cannot be returned in one of these forms comes with its
labelonly and is listed innotReproducible, outsidetable. Define it again, byidor withfilterTgl: sent unchanged, it is rejected withAE_ERR_405. - A
TABULATIONorREACH_TABLEcarries its effectiveweeksandweight; aTRENDorREACH_TRENDcarries them in each survey wave. A Reach table carries itstargetMediaanddiaryFilterswhen they were saved, and can also be sent toPOST /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 itsid(YYYY/WW),year,week, and its first and last day instartDateandendDate.weights: each weighting has itsid, itslabel(the survey's own, not translated), itsuniversewhen there is one, andisDefault.- 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
weightscan be sent asweightas it is returned: only itsidis read. AweightwithoutidisAE_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 emptyweeksis the same as not sending it, and a week sent twice isAE_ERR_400. - With several weeks, the weighted figures are the mean of the weeks;
Sampleand 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
tableTypethey areAE_ERR_400: aTRENDorREACH_TRENDtakes them in each survey wave (section 8.3). - In a
REACH_TABLEthey 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 ofROWSand the c-th item ofCOLUMNS, in the order ofdimensions.rowCountandcolumnCountgive the size.- Identify each matrix by its
items(one entry perPLANESaxis, with the axisidand the item of the slice), never by its position. - In
dimensions,PLANESlists only the selected items. - The cell depends on
dataType: a number (NUMBER), a formatted text (STRING) or an object{ "value", "formatted" }(FORMATTED_CELL). WithNUMBER, a cell that cannot be calculated (for example, when the target selects nobody) is the string"NaN", notnull. diagnosticsappears 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. Itslevelis 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. WithsliceId, you get that slice. GET .../tabulation/{elementId}/combinationslists every slice with itssliceId. Call it once, then pass eachsliceIdexplicitly in the query string of the tabulation call. AsliceIdis an opaque token: pass it unchanged.combinationsis the number of slices.indexCombinationis the position of the returned slice, starting at 1; it is reliable only when you passsliceId.selfTableLink,nextTableLinkandpreviousTableLinkreference the current, next and previous slice. Do not call them as they are: their last path segment is asliceId, which you pass in thesliceIdquery parameter.matrixListcontains exactly one matrix: the returned slice.- In a saved tabulation every cell is an object
{ "value", "formatted" }: readvaluefor the number.formattedis the text shown in the TOM web application, in the locale of the user.
11. Common errors
Status and errorCode | Cause |
|---|---|
400 AE_ERR_400 | An 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_401 | Invalid value of an enumerated field: tableType, dataType, the type or subtype of a variable, or the type of a category. |
400 AE_ERR_402 | In a REACH_TREND, a statistic outside the catalog of its axis. |
400 AE_ERR_404 | More 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_405 | target 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_410 | axisType 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_411 | A field that the object does not accept, also in weight, in a survey wave or in its weight. |
400 AE_ERR_412 | A 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_413 | dimensions is absent or empty, or a dimension has no axes. |
400 AE_ERR_414 | A CATEGORIES axis whose parentId is not a split VARIABLES axis. |
400 AE_ERR_416 | An unsupported variable. |
400 T_ERR_104, T_ERR_106, VA_ERR_101 | No statistics, a statistic that is not valid for the table type, or an unknown variable. |
400 VA_ERR_102 | A category the variable does not have, or a JOINT category without ids. |
400 CV_ERR_109 | A CUSTOM_VAR that cannot be resolved (outside a trend). |
400 TB_ERR_104 | No 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_113 | target or targetBase has an id that does not identify a saved target. |
400 TGL_ERR_101 | A filterTgl uses a variable or category that does not exist in the survey. |
400 TR_ERR_101, TR_ERR_103 | A TREND without a SOURCES axis, or without a DIFFERENCES axis. |
400 TR_ERR_105, TR_ERR_109 | A trend with no valid survey wave, or with none left after checking the variables of the table. |
400 TR_ERR_106 | trendCategoriesMode is not a valid value. |
401 SO_ERR_203 | The survey is not in your profile or does not exist. |
403 AE_ERR_408 | The user does not have the module that the table type needs: Reach for every Reach type, REACH_TREND included. |
422 TGL_INVALID | A filterTgl cannot be parsed, in target, targetBase or a TARGET_VAR. |
The full list is in Errors and troubleshooting.