Core concepts
This page defines the words the API uses. For each concept it says where it comes from and which operations take it as input, so you can follow an identifier from the call that returns it to the call that needs it.
1. The big picture
Survey (source)
├── Variables tree: folders → variables → categories → table axes, TGL expressions
└── Carriers tree: folders → carriers → rankings, evaluations, Reach, curves, optimizations
Workspace (a user's project)
├── Tabulations and Reach tables → read, edit, calculate again
├── Targets (named audiences, TGL) → filter calculations
├── User variables → table axes
└── Surveys attached to it
Calculations (on demand, nothing stored)
├── Tables: POST /table, POST /table/html, POST /reach
├── Media planning: ranking, evaluation, response curve
└── Optimization: asynchronous job (submit → poll → result)
2. Surveys
A survey is an audience study loaded in TOM: its respondents, the variables that describe them and the media they consume. It is also called a source. You can use only the surveys contracted for your user.
GET /api/v2/users/surveyslists them. Thecodeof a survey is thesurveyCodepath parameter of every survey-scoped endpoint.availableReachtells whether the survey is built on a consumption diary (radio, online and other diary studies). Only those support Reach.- Codes are opaque strings. Copy them from the survey list; do not build them.
3. Universe, sample and weighting
A survey interviews a sample of people and projects it to a universe: the population the survey describes. Respondents carry weights for that. Statistics come in both flavours: wTotal is the number of people, weighted and projected to the universe; Sample is the number of respondents, without weighting.
A target (section 9) narrows a calculation to part of the universe. A population base (targetBase) is different: it does not narrow the people counted, it chooses the reference universe of the percentages. Keep three ideas apart: the target is the audience you count, the base is the group a percentage is calculated over, and the universe is the whole population of the survey, the base when you send none.
4. Variables and categories
Variables are the questions and classifications of the survey, for example sex or age group. They are grouped in folders. A categorical variable has categories (Male, Female).
- A variable has a
type(VARin the tree) and asubtypethat tells how it is measured:SINGLE(one category per respondent),MULTIPLE(several categories per respondent),NUMERIC,REAL,LOGIC,TEXTorFREQUENCY.TEXTvariables cannot be tabulated. - A category id is unique only within its variable (
D1exists under many). In TGL expressions a category is writtenVARIABLE.CATEGORY, for exampleSEX.D1. - In a table request you can list the categories you want or omit them to use all. A
JOINTcategory merges several categories of one variable into one. GET /api/v2/survey/{surveyCode}/variablesreturns the whole tree.POST /api/v2/survey/{surveyCode}/tree/querybrowses and searches it level by level.
5. Carriers
A carrier is a media vehicle the survey measures: a TV channel, a radio station, a publication, a website. Carriers are grouped in folders; the tree query calls the carriers tree CARRIERS.
- The leaves of the tree have
type: CARRIER. A carrier is the unit you calculate with: rankings, evaluations, response curves and optimizations take carriers. - A folder (
type: FOLDER) groups carriers. Some operations accept folders and others treat anything that is not a carrier as a folder and ignore its insertions: read the operation you call. - A joint (
CARRIER_JOINT) is a set of carriers counted as one, listed by its memberids. Only some operations accept it, for example the media base of a Reach table. TOTAL_MEDIAis the aggregate of all the media of the survey. It is sent in aCARRIERSaxis (itsidis ignored) and comes back withTOTAL_MEDIAas itsid.- A carrier has no
subtype. It hasaudienceModel, the audience model the survey uses for it (informative), and, in the tree query, acarrierInfoobject with the details the survey defines. GET /api/v2/survey/{surveyCode}/carriersreturns the whole tree; the tree query can browse it too.
6. Statistics
A statistic is a measure a table shows in its cells. Which statistics exist depends on the kind of table, not on the survey:
| Family | Table types | Examples |
|---|---|---|
| Audience statistics | TABULATION, TREND | wTotal, ColPercentWeighted, Sample |
| Media statistics | RANKING, EVALUATION, BREAKDOWN_CARRIERS, DUPLICATIONS | COVER, GRP, OTS, CONTACT |
| Reach statistics | REACH_TABLE, REACH_DUPLICATION, REACH_TREND | They depend on the survey: read them, and the differences of a REACH_TREND, from GET /api/v2/survey/{surveyCode}/reach-capabilities. |
List the others with GET /api/v2/statistics?tableType=.... A statistic is identified by its id; labels and descriptions come in the user's language. The list follows the statistics the user has enabled in TOM.
7. Workspaces and elements
A workspace is a user's project in TOM. It holds:
- Elements saved by the user in the TOM web application or created through the API: tabulations, Reach tables, targets and user variables.
- The surveys attached to it. One of them is the active survey: the one selected in the web application.
surveyCodein a workspace describes the active one; the full list issurveys. - Sharing: a workspace can be shared with other users. You see the workspaces you own and the ones shared with you; you can write only to your own.
Saved studies (rankings, evaluations, breakdowns, duplications) are elements of a workspace too, but the API does not list them or read them back: it can only create a saved evaluation.
GET /api/v2/workspaces lists workspaces, and GET /api/v2/workspace/{workspaceId} lists the elements and surveys of one. An element id is the elementId of the element endpoints.
8. User variables
A user variable is a variable a user builds in the TOM web application from the survey variables (for example, a recode of age into three groups) and saves in a workspace. To tabulate one, put its id and subtype in a VARIABLES axis with type: CUSTOM_VAR. List them with GET .../user-vars.
9. Targets
A target is a named audience defined by a TGL expression, for example SEX.D1 AND EDA1.D3. It is saved in a workspace, not in a survey, and can be reused with any survey that has the variables it references. Calculations count only the respondents who match the target.
You can give a target in two ways: by the id of a saved target, or inline as a TGL expression (filterTgl). The rules differ by operation:
| Where | Rule |
|---|---|
target and targetBase (optional) of POST /table, /table/html, /reach, ranking, evaluation, saving an evaluation and response curve | id or filterTgl. If both are sent, filterTgl is used. With neither a non-blank id nor a non-blank filterTgl, it is 400 AE_ERR_405, with a message that names the field. A targetBase id is not looked up beforehand: if it cannot be resolved, the calculation engine returns its error, except in a TREND table, which leaves the base out and reports it in diagnostics. |
target and targetBase of an optimization (optional) | When present, exactly one of the saved target id or an inline expression (filterTgl). Both, or neither, is 400 AE_ERR_411, with a message that names the field. The target is a filter and the targetBase is the population base, independent of each other. |
A TARGET_VAR in a VARIABLES axis | id or filterTgl. Different values of both are 400 AE_ERR_416. |
In rankings, evaluations and response curves, a saved target id is looked up in all the workspaces visible to the user: 404 (AE_ERR_406) if it exists in none of them, 403 (AE_ERR_407) if it exists but is not visible to the user. The syntax of expressions is in the TGL guide.
10. Tables
A table crosses up to three dimensions: ROWS, COLUMNS and PLANES. Each dimension holds one or more typed axes (axisType): variables, statistics, categories of a split axis, carriers, survey waves and diary edges.
- The result is a set of matrices, a two-dimensional array of cells each.
matrixListhas one matrix per combination of selected items inPLANES. Each combination is a slice. - A tabulation is a saved table: a data cube with the same three dimensions. The saved tabulation endpoint returns one slice per call; the slices are listed by the combinations operation.
- A table type (
tableType) selects the kind of calculation:TABULATION(default),TREND,BREAKDOWN_CARRIERS,DUPLICATIONS,REACH_TABLE,REACH_DUPLICATIONandREACH_TREND.
See Building tables.
11. Plans and insertions
A media plan is a number of insertions (appearances of an advertisement) per carrier. Rankings, evaluations, response curves and optimizations share this vocabulary:
- In an evaluation or a response curve, each carrier has an
insertionsarray and each position of that array is a plan:[2, 1]puts the carrier twice in plan 1 and once in plan 2. - An optimization builds a plan: you give it candidate carriers and stop conditions, and it adds insertions step by step.
See Media planning and Asynchronous optimization.
12. Jobs
An optimization is the only asynchronous operation. Submitting it returns a jobId; you poll the status of the job and then read its result. A job belongs to the user of the API key. See Asynchronous optimization.
13. Diagnostics
Table responses can include an optional diagnostics object 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. Outside a trend, a user variable that cannot be resolved is an error (CV_ERR_109), not a diagnostic. It carries a severity level and a list of diagnostics. It is absent when there is nothing to report.
14. Identifier cheat sheet
| Identifier | Where it comes from | Where you use it |
|---|---|---|
surveyCode | code in GET /api/v2/users/surveys | The path of every survey-scoped endpoint. |
| Variable id and category id | id in the variables list, or code of a tree-query node | VARIABLES axes, categories, TGL expressions. |
| Carrier id | id of a CARRIER in the carriers list, or code of a tree-query node | CARRIERS axes, carriers of rankings, evaluations, curves and optimizations. |
Tree node id | A tree query | Only to navigate the tree (anchors of the next query). It is opaque and can change: store codes, not node ids. |
workspaceId | id in GET /api/v2/workspaces or POST /api/v2/workspace | The workspace endpoints. |
elementId | The element lists of GET /api/v2/workspace/{workspaceId} | The element, tabulation and target endpoints. |
Target id | The targets list, or the response of creating a target | target.id in calculations. |
User variable id | GET .../user-vars | CUSTOM_VAR items in VARIABLES axes. |
sliceId | itemCombinations[].sliceId of the combinations operation | The sliceId query parameter of the saved tabulation. |
jobId | The response of submitting an optimization | The status and result operations. |
Statistic id | GET /api/v2/statistics (or reach-capabilities for Reach) | STATISTICS axes and statistics lists. |
Identifiers are opaque strings. Do not build or parse them.