Skip to main content

Reach and duplication tables

Reach measures how many people a set of carriers reaches over the period of a consumption diary (radio, online and other diary studies), and how much time they spend with them. The API offers three Reach modes:

  • REACH_TABLE: reach and time statistics of each carrier, optionally broken down by diary edges such as the day, the device or the time of day.
  • REACH_DUPLICATION: the audience overlap between carriers.
  • REACH_TREND: the statistics of a REACH_TABLE compared across survey waves (section 4.1).

All three go through the same request model as a regular table (see Building tables), with the axes and statistics that are specific to Reach.

1. Prerequisites​

  1. A diary survey. Check that the survey has availableReach: true in GET /api/v2/users/surveys. Any other survey is rejected with 400 RC_ERR_100.
  2. The Reach module. The user behind the API key needs it, or the call gets 403 AE_ERR_408.
  3. The capabilities of the survey. A survey offers only some of the statistics, and its diary edges and value codes can change when it is reloaded. Read them with GET /api/v2/survey/{surveyCode}/reach-capabilities for each survey you work with. The ids of the statistics do not change their name, but do not assume that a survey offers all of them.
  4. Carriers. Take carrier ids from GET /api/v2/survey/{surveyCode}/carriers.

2. Discover the capabilities​

GET /api/v2/survey/{surveyCode}/reach-capabilities returns:

  • statistics: one list per mode, keyed REACH_TABLE, REACH_DUPLICATION and REACH_TREND. Send the id of a statistic in the STATISTICS axis of a request with the same tableType. The REACH_TREND list is the REACH_TABLE one: a Reach trend calculates the statistics of a Reach table.
    • In REACH_TABLE and REACH_DUPLICATION, an id of the other mode is left out without an error, and an id the calculation engine does not know returns T_ERR_106.
    • In REACH_TREND, an id outside the list returns 400 AE_ERR_402 before calculating. An id of the list that the survey does not offer is left out, as in REACH_TABLE.
  • differences: the statistics of the DIFFERENCES axis, keyed REACH_TREND. They are the differences between survey waves (TrendTotal, AbsFirst, AbsPrev, PrcFirst, PrcPrev, Titles), the same ones as a TREND table. Send their id in the DIFFERENCES axis of a REACH_TREND.
  • diaryEdges: the dimensions of the diary, such as the day of the week, the device or the time of day. The axisType of each edge tells you how to use it:
    • CUSTOM_DIARY_EDGE: the edge lists its values. A value with combines is a group of the codes it lists (for example, Weekend groups Saturday and Sunday).
    • TIME_DIARY_EDGE: the edge describes the time of day in time: defaultStart, the allowed step values in allowedStepsRanges and whether supportsExplicitRanges is true.
    • An edge that has a filter can also restrict the whole calculation (section 5).
{
"statistics": {
"REACH_TABLE": [
{ "id": "Reach", "label": "Reach", "description": "Persons reached at least once during the diary period" },
{ "id": "ReachPercent", "label": "Reach %", "description": "Reach as a percentage of the universe" }
],
"REACH_DUPLICATION": [
{ "id": "DupReachPct", "label": "Reach %", "description": "Combined unique reach as percentage of the universe" }
],
"REACH_TREND": [
{ "id": "Reach", "label": "Reach", "description": "Persons reached at least once during the diary period" },
{ "id": "ReachPercent", "label": "Reach %", "description": "Reach as a percentage of the universe" }
]
},
"differences": {
"REACH_TREND": [
{ "id": "TrendTotal", "label": "Total", "description": "Value of each survey wave." },
{ "id": "AbsPrev", "label": "Difference with the previous wave", "description": "Difference between the value of a survey wave and the one of the previous wave." }
]
},
"diaryEdges": [
{
"name": "day",
"title": "Day of the week",
"axisType": "CUSTOM_DIARY_EDGE",
"values": [
{ "code": 1, "label": "Monday" },
{ "code": 8, "label": "Weekend", "combines": [6, 7] }
]
},
{
"name": "time",
"title": "Time of day",
"axisType": "TIME_DIARY_EDGE",
"time": { "defaultStart": "06:00", "allowedStepsRanges": [{ "step": 60, "label": "1 hour" }], "supportsExplicitRanges": true }
}
]
}

The response above is abridged and its names, codes and labels are illustrative: each survey defines its own.

3. Choose the operation​

Two operations calculate Reach tables. Both take the same body, Reach fields included, and return the same response model. They differ in what else they accept:

OperationWhat it accepts
POST /api/v2/reach/{surveyCode}Only the Reach modes. It also accepts base, the deprecated name of targetBase.
POST /api/v2/table/{surveyCode}Every table type. With tableType REACH_TABLE, REACH_DUPLICATION or REACH_TREND it accepts targetMedia and diaryFilters; with any other tableType they return AE_ERR_400 and the message names the field. Its /html variant takes the same body and returns the table as HTML.

Set tableType to choose the mode. On POST /api/v2/reach/{surveyCode} the tableType is required and must be REACH_TABLE, REACH_DUPLICATION or REACH_TREND (case-sensitive): without it, or with any other value, the request is rejected with AE_ERR_401 (HTTP 400) and the message lists the three valid values. On the table operation, tableType defaults to TABULATION, so set it.

A saved Reach table. A Reach table read with GET /api/v2/workspace/{workspaceId}/element/{elementId} comes with its targetMedia and diaryFilters when they were saved, and can be sent unchanged to either operation (see Reuse a saved table). Two things to check before you send it:

  • Send it to the surveyCode that the element returns. In a REACH_TREND the survey of the path acts as the active survey of the comparison (section 4.1), so another survey can give other figures.
  • Read notReproducible. An item of a CUSTOM_DIARY_EDGE axis that grouped several values (for example Monday to Friday) is left out of the axis and marked with field diaryEdge and reason GROUPED_ITEM, once however many axes had one; sent back, the table is calculated without it. The total item of a diary edge axis, which a request cannot ask for, is marked with reason TOTAL_ITEM: sent back, the table has that row or column fewer.

4. Axes of a Reach table​

  • CARRIERS: the carriers to measure. Each entry is { "id": "...", "type": "CARRIER" }; type can be omitted.
  • STATISTICS: the statistics, by id, from the capabilities of the same mode. Only the statistics you request are returned, in the order you send them. In REACH_TABLE and REACH_DUPLICATION, an id of another Reach mode is left out without an error and an id the calculation engine does not know returns T_ERR_106; if none is valid, the first statistic of the mode is returned instead. A REACH_TREND checks its statistics before calculating (section 4.1).
  • SOURCES and DIFFERENCES (REACH_TREND only): the survey waves to compare and the differences between them (section 4.1).
  • CUSTOM_DIARY_EDGE: breaks the result down by the values of an edge. edge is the edge name and items are the value codes, sent as numeric strings, for example ["1", "2"].
  • TIME_DIARY_EDGE: breaks the result down by time slots. edge is the name of the time edge, and time defines the slots either as explicit ranges of HH:mm times, or as a step in minutes from from to to. When ranges is not empty it is used and step, from and to are ignored. A to earlier than from crosses midnight, from equal to to covers the full 24 hours, and the last slot is shorter when the span is not a multiple of step. Take the step from allowedStepsRanges.
  • VARIABLES: survey variables, to break the result down by an audience variable.

REACH_TABLE usually puts the carriers in ROWS and the statistics in COLUMNS. REACH_DUPLICATION puts carriers in two CARRIERS axes, in ROWS and COLUMNS, so that each cell is a pair, and the statistics in PLANES. Statistics of the duplication mode have ids such as DupReachPct.

A minimal Reach table, with the reach and the reach percentage of two carriers:

{
"tableType": "REACH_TABLE",
"dimensions": [
{
"id": "ROWS",
"axis": [
{
"axisType": "CARRIERS",
"carriers": [
{ "id": "RADIO_STATION_1", "type": "CARRIER" },
{ "id": "RADIO_STATION_2", "type": "CARRIER" }
]
}
]
},
{
"id": "COLUMNS",
"axis": [{ "axisType": "STATISTICS", "statistics": [{ "id": "Reach" }, { "id": "ReachPercent" }] }]
}
]
}

An overlap table between the same carriers:

{
"tableType": "REACH_DUPLICATION",
"dimensions": [
{
"id": "ROWS",
"axis": [
{
"axisType": "CARRIERS",
"carriers": [
{ "id": "RADIO_STATION_1", "type": "CARRIER" },
{ "id": "RADIO_STATION_2", "type": "CARRIER" }
]
}
]
},
{
"id": "COLUMNS",
"axis": [
{
"axisType": "CARRIERS",
"carriers": [
{ "id": "RADIO_STATION_1", "type": "CARRIER" },
{ "id": "RADIO_STATION_2", "type": "CARRIER" }
]
}
]
},
{ "id": "PLANES", "axis": [{ "axisType": "STATISTICS", "statistics": [{ "id": "DupReachPct" }] }] }
]
}

Time slots, explicit this time:

{
"axisType": "TIME_DIARY_EDGE",
"edge": "time",
"time": { "ranges": [{ "from": "06:00", "to": "10:00" }, { "from": "16:00", "to": "20:00" }] }
}

4.1. Reach trend​

A REACH_TREND takes the axes of a REACH_TABLE (carriers, statistics and, if you want, variables and diary edges) plus a SOURCES axis with the survey waves and a DIFFERENCES axis with the differences between them.

  • Required axes. SOURCES, DIFFERENCES and CARRIERS. Without one of them, the request is rejected with AE_ERR_412, naming the type of axis, before calculating. The CARRIERS axis goes in ROWS or COLUMNS: in PLANES it is rejected with AE_ERR_410.
  • Statistics and differences. The STATISTICS axis takes the ids of statistics.REACH_TREND and the DIFFERENCES axis those of differences.REACH_TREND, both from the capabilities. Any other id is rejected with AE_ERR_402, naming the ids, before calculating. An id of the list that the survey does not offer is left out, as in a REACH_TABLE.
  • Survey waves. Each item of the SOURCES axis is a wave with id and, optionally, selected, weeks and weight, with the rules of a TREND table (see Trend across survey waves). A survey without weeks ignores weeks, and a survey without weightings ignores weight. A wave without weight gets no weighting. weeks and weight at the top level of the body are rejected with AE_ERR_400.
  • Weeks and weighting do not change the figures. They only decide whether a wave is calculated: a wave with weeks or a weighting that its survey does not have, or without weeks for a survey that has them, is discarded with a TR_ERR_107 diagnostic. The Reach calculation does not receive them, so two waves of the same survey that differ only in their weeks or their weighting give identical columns.
  • The survey of the path. surveyCode acts as the active survey of the comparison: it decides how the STATISTICS axis is reconciled with its catalog, which categories enter with the default trendCategoriesMode, and whether the target is discarded. The same body sent to another survey can give other figures.
  • A survey of the path without Reach is rejected with 400 RC_ERR_100, with the code and the message of a REACH_TABLE, before calculating. When it does not have the items of a diary edge axis or the target media requested, the request fails at once with RC_ERR_106, RC_ERR_107 or RC_ERR_108. A diary filter that it cannot apply is left out without an error.
  • Other survey waves that cannot be calculated come without values and with a WARNING diagnostic, and the response is 200. A wave whose survey does not have the items of a diary edge axis comes without values and without a diagnostic.
  • Target. A saved target that exists but does not resolve in the survey of the path is discarded for every wave, with an ERROR diagnostic, and the response is 200 with the whole population, as in a TREND table. An id that does not identify a saved target returns 400 TG_ERR_113, as in a REACH_TABLE. A filterTgl with a variable that the survey of the path does not have is rejected with TGL_ERR_101. A target that does not resolve in another wave leaves only that wave without values.
  • Carriers. A CARRIER_JOINT is calculated in each wave that has all its carriers. A carrier that no wave has comes without values and without a diagnostic: check the ids with the carriers list.
  • Categories. extraParams.trendCategoriesMode applies as in a TREND table; an invalid value returns TR_ERR_106.

Diagnostics of a survey wave, in a 200 response:

errorCodeWhen
TR_ERR_107The wave is not available to the user, or its weeks or its weighting are not valid.
RC_ERR_112, RC_ERR_113, RC_ERR_115, RC_ERR_116The wave cannot be calculated in Reach: its survey does not have the carriers, the diary filters or the target media requested, or it has no Reach data.

The reach of two carriers in two survey waves, restricted to two devices. The ids come from the capabilities and from GET /api/v2/survey/{surveyCode}/weeks-and-weights. The DIFFERENCES axis is in PLANES with two selected items, so the response has one matrix for TrendTotal and another for AbsPrev, the difference with the previous wave. An item of a PLANES axis that is not selected is not returned.

{
"tableType": "REACH_TREND",
"dimensions": [
{
"id": "ROWS",
"axis": [
{
"axisType": "CARRIERS",
"carriers": [
{ "id": "RADIO_STATION_1", "type": "CARRIER" },
{ "id": "RADIO_STATION_2", "type": "CARRIER" }
]
}
]
},
{
"id": "COLUMNS",
"axis": [
{
"axisType": "SOURCES",
"sources": [
{ "id": "DIARY_DEMO_2024", "weeks": ["2024/40"], "weight": { "id": "W1" } },
{ "id": "DIARY_DEMO_2025", "weeks": ["2025/40"], "weight": { "id": "W1" } }
]
}
]
},
{
"id": "PLANES",
"axis": [
{ "axisType": "STATISTICS", "statistics": [{ "id": "Reach", "selected": true }] },
{ "axisType": "DIFFERENCES", "differences": [{ "id": "TrendTotal", "selected": true }, { "id": "AbsPrev", "selected": true }] }
]
}
],
"diaryFilters": [{ "edge": "device", "values": ["1", "2"] }]
}

5. Audience, population base, media base and diary filters​

  • target: the audience filter. The calculation counts only the respondents who match it. Send a saved target id or an inline TGL expression in filterTgl; with both, filterTgl wins. A target with neither a non-blank id nor a non-blank filterTgl is rejected with AE_ERR_405. An id that does not identify a saved target is rejected with 400 TG_ERR_113, in every mode, REACH_TREND included; for a saved target that does not resolve in a REACH_TREND, see section 4.1.
  • targetBase: the population base, accepted by both operations. It fixes the reference universe of the percentages in the result, for example the people of one gender when you want percentages of that group. Send a saved target id or an inline TGL expression in filterTgl; with both, filterTgl wins. A targetBase with neither a non-blank id nor a non-blank filterTgl is rejected with AE_ERR_405, and an id that does not identify a saved target with 400 TG_ERR_113, in every mode. A base that cannot be resolved (an unknown variable in the expression, or a target id that the user cannot see) returns the error of the calculation engine, never a result over the whole universe. Without targetBase, the percentages are calculated over the whole universe of the survey. base is a deprecated name of targetBase that is still accepted only by POST /reach (see Deprecated names); do not send both, because the last one in the body is used.
  • targetMedia: the set of media that counts as 100% in share statistics. Entries can be individual carriers (type omitted or CARRIER), folders (FOLDER, as returned by the carriers endpoint) and joints (CARRIER_JOINT with its member ids, counted as their members). Any other type is read as a single carrier. Without it, shares are calculated over all the media of the survey. A carrier that the survey does not have is rejected with RC_ERR_108.
  • diaryFilters: restricts the whole calculation to some values of an edge that has a filter in the capabilities. edge is the edge name and values are the value codes to keep, sent as strings. A filter that does not match the survey, such as an unknown edge or a code the edge does not have, is not guaranteed to be rejected: it can be ignored, and the edge then keeps its default selection (filter.values).
  • weeks and weight: in a REACH_TABLE they are accepted and checked against the survey (AE_ERR_400 for a value it does not have), but they do not change the Reach figures: the Reach calculation does not receive them. REACH_DUPLICATION and REACH_TREND reject them with AE_ERR_400; a REACH_TREND takes them in each survey wave (section 4.1). Get the valid values from GET /api/v2/survey/{surveyCode}/weeks-and-weights.

targetMedia and diaryFilters apply in the three Reach modes, on both operations (section 3).

{
"target": { "filterTgl": "EDA1.D3" },
"targetBase": { "filterTgl": "SEX.D1" },
"targetMedia": [{ "id": "RADIO_FOLDER_1", "type": "FOLDER" }],
"diaryFilters": [{ "edge": "device", "values": ["1", "2"] }]
}

6. Layout of the response​

The response has the same shape as the one of a regular table: dimensions returns the axes as calculated and matrixList the values.

  • Statistics in COLUMNS: one matrix, rows by columns.
  • Statistics in PLANES with more than one marked "selected": true: one matrix per selected statistic, each identified by its items.
  • REACH_TREND: shaped like the response of a TREND table. The SOURCES and DIFFERENCES axes come in dimensions, and each survey wave carries its weeks and weight when it had them. Carriers and axes come with their labels, as in a REACH_TABLE.

dataType, locale and decimals control the cell format as in the table operation, and diagnostics appears only when the calculation has something to report.

7. Errors​

Status and errorCodeCause
400 RC_ERR_100The survey does not support Reach. In a REACH_TREND, the API checks the survey of the path before calculating and returns the code and the message of a REACH_TABLE.
400 RC_ERR_106, RC_ERR_107A diary edge axis uses values or time ranges that the survey does not have (including an explicit range that is not a valid HH:mm).
400 RC_ERR_108targetMedia includes carriers that the survey does not have.
400 RD_ERR_100REACH_DUPLICATION without a second CARRIERS axis.
400 T_ERR_104, T_ERR_106No statistics were requested, or (REACH_TABLE, REACH_DUPLICATION) a statistic id that the calculation engine does not know.
400 EV_ERR_108REACH_TABLE without carriers.
400 SP_ERR_101(REACH_TABLE) A carrier id that the survey does not have.
400 TR_ERR_105(REACH_TREND) No survey wave is valid by availability, weeks or weighting.
400 TR_ERR_106(REACH_TREND) trendCategoriesMode is not a valid value.
400 TR_ERR_109(REACH_TREND) No survey wave is left after checking the variables of the table and the Reach checks of each wave.
400 AE_ERR_400weeks or weight of the table in a REACH_DUPLICATION or REACH_TREND, or a week or a weighting the survey does not have. On the table operation, targetMedia or diaryFilters with a tableType that is not Reach. In a TIME_DIARY_EDGE axis without ranges, a time.step that is not positive, or a time.from or time.to that is not HH:mm. Also a negative decimals or a value of the wrong JSON type. The message names the field or the value.
400 AE_ERR_401tableType is missing or is not REACH_TABLE, REACH_DUPLICATION or REACH_TREND, or another enumerated field has an invalid value. The message lists the valid values.
400 AE_ERR_402(REACH_TREND) A statistic or a difference outside the catalog of its axis.
400 AE_ERR_405target or targetBase has neither a non-blank id nor a non-blank filterTgl.
400 TG_ERR_113target or targetBase has an id that does not identify a saved target, in every mode, REACH_TREND included.
400 TGL_ERR_101A filterTgl uses a variable or category that the survey does not have.
400 AE_ERR_412(REACH_TREND) No SOURCES, DIFFERENCES or CARRIERS axis. Also a weight without id, in the table or in a survey wave, and a TIME_DIARY_EDGE axis without ranges and without time.step, time.from or time.to.
400 AE_ERR_404, AE_ERR_409 to AE_ERR_414, AE_ERR_416A malformed request, including the CARRIERS axis of a REACH_TREND in PLANES (AE_ERR_410) and an unknown field in a survey wave or in its weight (AE_ERR_411): see Building tables.
400 SO_ERR_201The survey is disabled or being loaded.
401 SO_ERR_203The survey does not exist or is not in your profile.
403 AE_ERR_408The user does not have the Reach module.
422 TGL_INVALIDA filterTgl cannot be parsed.
500 GEN_ERR_500Unexpected error.

A discarded or uncalculated survey wave of a REACH_TREND is not an error: it is a diagnostic of a 200 response (section 4.1). Errors raised by the calculation engine keep their own errorCode, with an errorMessage in the language of the user. See Errors and troubleshooting.