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 aREACH_TABLEcompared 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
- A diary survey. Check that the survey has
availableReach: trueinGET /api/v2/users/surveys. Any other survey is rejected with400RC_ERR_100. - The Reach module. The user behind the API key needs it, or the call gets
403AE_ERR_408. - 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-capabilitiesfor 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. - 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, keyedREACH_TABLE,REACH_DUPLICATIONandREACH_TREND. Send theidof a statistic in theSTATISTICSaxis of a request with the sametableType. TheREACH_TRENDlist is theREACH_TABLEone: a Reach trend calculates the statistics of a Reach table.- In
REACH_TABLEandREACH_DUPLICATION, an id of the other mode is left out without an error, and an id the calculation engine does not know returnsT_ERR_106. - In
REACH_TREND, an id outside the list returns400AE_ERR_402before calculating. An id of the list that the survey does not offer is left out, as inREACH_TABLE.
- In
differences: the statistics of theDIFFERENCESaxis, keyedREACH_TREND. They are the differences between survey waves (TrendTotal,AbsFirst,AbsPrev,PrcFirst,PrcPrev,Titles), the same ones as aTRENDtable. Send theiridin theDIFFERENCESaxis of aREACH_TREND.diaryEdges: the dimensions of the diary, such as the day of the week, the device or the time of day. TheaxisTypeof each edge tells you how to use it:CUSTOM_DIARY_EDGE: the edge lists itsvalues. A value withcombinesis a group of the codes it lists (for example, Weekend groups Saturday and Sunday).TIME_DIARY_EDGE: the edge describes the time of day intime:defaultStart, the allowedstepvalues inallowedStepsRangesand whethersupportsExplicitRangesistrue.- An edge that has a
filtercan 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:
| Operation | What 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
surveyCodethat the element returns. In aREACH_TRENDthe 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 aCUSTOM_DIARY_EDGEaxis that grouped several values (for example Monday to Friday) is left out of the axis and marked withfielddiaryEdgeandreasonGROUPED_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 withreasonTOTAL_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" };typecan 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. InREACH_TABLEandREACH_DUPLICATION, an id of another Reach mode is left out without an error and an id the calculation engine does not know returnsT_ERR_106; if none is valid, the first statistic of the mode is returned instead. AREACH_TRENDchecks its statistics before calculating (section 4.1).SOURCESandDIFFERENCES(REACH_TRENDonly): 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.edgeis the edgenameanditemsare the valuecodes, sent as numeric strings, for example["1", "2"].TIME_DIARY_EDGE: breaks the result down by time slots.edgeis thenameof the time edge, andtimedefines the slots either as explicitrangesofHH:mmtimes, or as astepin minutes fromfromtoto. Whenrangesis not empty it is used andstep,fromandtoare ignored. Atoearlier thanfromcrosses midnight,fromequal totocovers the full 24 hours, and the last slot is shorter when the span is not a multiple ofstep. Take thestepfromallowedStepsRanges.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,DIFFERENCESandCARRIERS. Without one of them, the request is rejected withAE_ERR_412, naming the type of axis, before calculating. TheCARRIERSaxis goes inROWSorCOLUMNS: inPLANESit is rejected withAE_ERR_410. - Statistics and differences. The
STATISTICSaxis takes the ids ofstatistics.REACH_TRENDand theDIFFERENCESaxis those ofdifferences.REACH_TREND, both from the capabilities. Any other id is rejected withAE_ERR_402, naming the ids, before calculating. An id of the list that the survey does not offer is left out, as in aREACH_TABLE. - Survey waves. Each item of the
SOURCESaxis is a wave withidand, optionally,selected,weeksandweight, with the rules of aTRENDtable (see Trend across survey waves). A survey without weeks ignoresweeks, and a survey without weightings ignoresweight. A wave withoutweightgets no weighting.weeksandweightat the top level of the body are rejected withAE_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_107diagnostic. 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.
surveyCodeacts as the active survey of the comparison: it decides how theSTATISTICSaxis is reconciled with its catalog, which categories enter with the defaulttrendCategoriesMode, 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
400RC_ERR_100, with the code and the message of aREACH_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 withRC_ERR_106,RC_ERR_107orRC_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
WARNINGdiagnostic, and the response is200. 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
ERRORdiagnostic, and the response is200with the whole population, as in aTRENDtable. Anidthat does not identify a saved target returns400TG_ERR_113, as in aREACH_TABLE. AfilterTglwith a variable that the survey of the path does not have is rejected withTGL_ERR_101. A target that does not resolve in another wave leaves only that wave without values. - Carriers. A
CARRIER_JOINTis 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.trendCategoriesModeapplies as in aTRENDtable; an invalid value returnsTR_ERR_106.
Diagnostics of a survey wave, in a 200 response:
errorCode | When |
|---|---|
TR_ERR_107 | The 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_116 | The 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 targetidor an inline TGL expression infilterTgl; with both,filterTglwins. Atargetwith neither a non-blankidnor a non-blankfilterTglis rejected withAE_ERR_405. Anidthat does not identify a saved target is rejected with400TG_ERR_113, in every mode,REACH_TRENDincluded; for a saved target that does not resolve in aREACH_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 targetidor an inline TGL expression infilterTgl; with both,filterTglwins. AtargetBasewith neither a non-blankidnor a non-blankfilterTglis rejected withAE_ERR_405, and anidthat does not identify a saved target with400TG_ERR_113, in every mode. A base that cannot be resolved (an unknown variable in the expression, or a targetidthat the user cannot see) returns the error of the calculation engine, never a result over the whole universe. WithouttargetBase, the percentages are calculated over the whole universe of the survey.baseis a deprecated name oftargetBasethat is still accepted only byPOST /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 (typeomitted orCARRIER), folders (FOLDER, as returned by the carriers endpoint) and joints (CARRIER_JOINTwith its memberids, counted as their members). Any othertypeis 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 withRC_ERR_108.diaryFilters: restricts the whole calculation to some values of an edge that has afilterin the capabilities.edgeis the edgenameandvaluesare the valuecodes 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).weeksandweight: in aREACH_TABLEthey are accepted and checked against the survey (AE_ERR_400for a value it does not have), but they do not change the Reach figures: the Reach calculation does not receive them.REACH_DUPLICATIONandREACH_TRENDreject them withAE_ERR_400; aREACH_TRENDtakes them in each survey wave (section 4.1). Get the valid values fromGET /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
PLANESwith more than one marked"selected": true: one matrix per selected statistic, each identified by itsitems. REACH_TREND: shaped like the response of aTRENDtable. TheSOURCESandDIFFERENCESaxes come indimensions, and each survey wave carries itsweeksandweightwhen it had them. Carriers and axes come with their labels, as in aREACH_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 errorCode | Cause |
|---|---|
400 RC_ERR_100 | The 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_107 | A 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_108 | targetMedia includes carriers that the survey does not have. |
400 RD_ERR_100 | REACH_DUPLICATION without a second CARRIERS axis. |
400 T_ERR_104, T_ERR_106 | No statistics were requested, or (REACH_TABLE, REACH_DUPLICATION) a statistic id that the calculation engine does not know. |
400 EV_ERR_108 | REACH_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_400 | weeks 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_401 | tableType 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_405 | target or targetBase has neither a non-blank id nor a non-blank filterTgl. |
400 TG_ERR_113 | target or targetBase has an id that does not identify a saved target, in every mode, REACH_TREND included. |
400 TGL_ERR_101 | A 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_416 | A 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_201 | The survey is disabled or being loaded. |
401 SO_ERR_203 | The survey does not exist or is not in your profile. |
403 AE_ERR_408 | The user does not have the Reach module. |
422 TGL_INVALID | A filterTgl cannot be parsed. |
500 GEN_ERR_500 | Unexpected 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.