Skip to main content

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/surveys lists them. The code of a survey is the surveyCode path parameter of every survey-scoped endpoint.
  • availableReach tells 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 (VAR in the tree) and a subtype that tells how it is measured: SINGLE (one category per respondent), MULTIPLE (several categories per respondent), NUMERIC, REAL, LOGIC, TEXT or FREQUENCY. TEXT variables cannot be tabulated.
  • A category id is unique only within its variable (D1 exists under many). In TGL expressions a category is written VARIABLE.CATEGORY, for example SEX.D1.
  • In a table request you can list the categories you want or omit them to use all. A JOINT category merges several categories of one variable into one.
  • GET /api/v2/survey/{surveyCode}/variables returns the whole tree. POST /api/v2/survey/{surveyCode}/tree/query browses 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 member ids. Only some operations accept it, for example the media base of a Reach table.
  • TOTAL_MEDIA is the aggregate of all the media of the survey. It is sent in a CARRIERS axis (its id is ignored) and comes back with TOTAL_MEDIA as its id.
  • A carrier has no subtype. It has audienceModel, the audience model the survey uses for it (informative), and, in the tree query, a carrierInfo object with the details the survey defines.
  • GET /api/v2/survey/{surveyCode}/carriers returns 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:

FamilyTable typesExamples
Audience statisticsTABULATION, TRENDwTotal, ColPercentWeighted, Sample
Media statisticsRANKING, EVALUATION, BREAKDOWN_CARRIERS, DUPLICATIONSCOVER, GRP, OTS, CONTACT
Reach statisticsREACH_TABLE, REACH_DUPLICATION, REACH_TRENDThey 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. surveyCode in a workspace describes the active one; the full list is surveys.
  • 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:

WhereRule
target and targetBase (optional) of POST /table, /table/html, /reach, ranking, evaluation, saving an evaluation and response curveid 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 axisid 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. matrixList has one matrix per combination of selected items in PLANES. 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_DUPLICATION and REACH_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 insertions array 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​

IdentifierWhere it comes fromWhere you use it
surveyCodecode in GET /api/v2/users/surveysThe path of every survey-scoped endpoint.
Variable id and category idid in the variables list, or code of a tree-query nodeVARIABLES axes, categories, TGL expressions.
Carrier idid of a CARRIER in the carriers list, or code of a tree-query nodeCARRIERS axes, carriers of rankings, evaluations, curves and optimizations.
Tree node idA tree queryOnly to navigate the tree (anchors of the next query). It is opaque and can change: store codes, not node ids.
workspaceIdid in GET /api/v2/workspaces or POST /api/v2/workspaceThe workspace endpoints.
elementIdThe element lists of GET /api/v2/workspace/{workspaceId}The element, tabulation and target endpoints.
Target idThe targets list, or the response of creating a targettarget.id in calculations.
User variable idGET .../user-varsCUSTOM_VAR items in VARIABLES axes.
sliceIditemCombinations[].sliceId of the combinations operationThe sliceId query parameter of the saved tabulation.
jobIdThe response of submitting an optimizationThe status and result operations.
Statistic idGET /api/v2/statistics (or reach-capabilities for Reach)STATISTICS axes and statistics lists.

Identifiers are opaque strings. Do not build or parse them.