Skip to main content

Calculate a Reach table

POST 

/api/v2/reach/:surveyCode

Calculates a Reach table on a consumption-diary survey: how many people your media carriers reach over the diary period and how long they spend with them.

It works on surveys built on a consumption diary (radio, online and other diary studies). The result can be broken down by diary edges such as the day, the device or the time of day, and restricted to part of the diary.

POST /api/v2/table/{surveyCode} and its /html variant take the same body with a Reach tableType, targetMedia and diaryFilters included; this endpoint accepts only the Reach modes. Both endpoints share the request axes and the response model, and a Reach table read with GET /api/v2/workspace/{workspaceId}/element/{elementId} can be sent unchanged to either.

Before you call it​

  1. Check that the survey has availableReach: true in GET /api/v2/users/surveys.
  2. Read GET /api/v2/survey/{surveyCode}/reach-capabilities for the statistic ids of each mode, the differences of a REACH_TREND and the diary edge names and value codes.
  3. Take carrier ids from GET /api/v2/survey/{surveyCode}/carriers.
  4. The user behind the API key needs the Reach module.

Modes​

tableType is required and must be REACH_TABLE, REACH_DUPLICATION or REACH_TREND, which choose the mode. Without it, or with any other value, the request is rejected with AE_ERR_401 (HTTP 400), and the message lists the valid values. Values are case-sensitive. The Reach-specific fields apply in these three modes.

  • REACH_TABLE: reach and time statistics of each carrier. Put the carriers in a CARRIERS axis (usually ROWS) and the statistics in a STATISTICS axis (usually COLUMNS). Add CUSTOM_DIARY_EDGE, TIME_DIARY_EDGE or VARIABLES axes to break the result down.
  • REACH_DUPLICATION: audience overlap between carriers. Put carriers in two CARRIERS axes, in ROWS and COLUMNS, so that each cell is a pair, and the statistics in PLANES.
  • REACH_TREND: the statistics of a REACH_TABLE compared across survey waves. It takes the axes of a REACH_TABLE (carriers, statistics and, if you want, variables and diary edge axes) plus a SOURCES axis with the survey waves and a DIFFERENCES axis with the differences between them. See Reach trend.

Use statistic ids of the same mode, as listed by reach-capabilities. 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 is checked before calculating: see Reach trend.

Reach trend (REACH_TREND)​

  • Required axes. A SOURCES axis, a DIFFERENCES axis and a CARRIERS axis. 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 the request is rejected with AE_ERR_410.
  • Statistics. The STATISTICS axis takes the statistics of a REACH_TABLE (statistics.REACH_TREND of reach-capabilities) and the DIFFERENCES axis the differences of a trend (differences.REACH_TREND). Any other id is rejected with AE_ERR_402, naming the ids, before calculating. An id of the catalog that the survey does not offer is left out, as in a REACH_TABLE.
  • Survey waves. Each item of the SOURCES axis is a survey wave with id and, optionally, selected, weeks and weight, with the rules of a TREND table (see POST /api/v2/table/{surveyCode}). The weeks and the weighting of a wave decide whether the wave is calculated, but they do not change the figures: the Reach engine does not receive them. Two waves of the same survey that differ only in their weeks or weighting give identical columns. A wave without weight gets no weighting. weeks and weight at the top level of the body are rejected with AE_ERR_400.
  • 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. To get the figures of a saved element, send it to its surveyCode.
  • A survey of the path without Reach is rejected with 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, as in a REACH_TABLE.
  • 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. A diary filter that the survey of the path cannot apply is left out without an error.
  • Target. A saved target (id) 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, while a TREND table discards it with a diagnostic. A filterTgl with a variable that the survey of the path does not have is rejected with TGL_ERR_101, also as in a TREND table. diagnostics.level is then ERROR. A target that does not resolve in another wave leaves only that wave without values.
  • Carriers. A CARRIER_JOINT is calculated in each survey wave that has all its carriers, with the figures of a REACH_TABLE of that wave. A carrier that no survey wave has comes without values and without a diagnostic: check the ids with GET /api/v2/survey/{surveyCode}/carriers.
  • Categories. extraParams.trendCategoriesMode applies as in a TREND table; an invalid value returns TR_ERR_106.
  • Response. 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.

Diagnostics of a survey wave, in a 200 response:

errorCodeWhen
TR_ERR_107The wave is not available to the user, it has no weeks in a survey with weeks, or it has a week or a weighting the survey does not have.
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.

Diary edge axes​

  • CUSTOM_DIARY_EDGE: edge is the edge name and items are value codes, sent as numeric strings (for example "1").
  • TIME_DIARY_EDGE: 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 time.allowedStepsRanges.

Diary filters​

diaryFilters restricts the whole calculation to some values of an edge that has a filter in reach-capabilities: edge is the edge name and values are the value codes to keep, sent as strings. Take both from reach-capabilities. 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).

Audience, population base and media base​

  • target: 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 (HTTP 400).
  • targetBase: the population base. It fixes the reference universe of the percentages in the result. 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 (HTTP 400). A base that cannot be resolved returns the error of the engine, never a result over the whole universe. Without it, the percentages are calculated over the whole universe of the survey.
  • targetMedia: the set of media that counts as 100% in share statistics: 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.

Weeks and weighting​

In a REACH_TABLE, weeks and weight of the table 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 engine does not receive them. REACH_DUPLICATION and REACH_TREND reject them with AE_ERR_400; a REACH_TREND takes them in each survey wave. Get the valid values from GET /api/v2/survey/{surveyCode}/weeks-and-weights.

Response​

The response has the same shape as the one of POST /api/v2/table/{surveyCode}. dimensions returns the axes as calculated, and matrixList the values:

  • Statistics in COLUMNS: one matrix, rows × columns.
  • Statistics in PLANES with more than one marked "selected": true: one matrix per selected statistic, each identified by its items.

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

Deprecated names​

The names that the table endpoint still accepts for carriers are also accepted here (see POST /api/v2/table/{surveyCode}), and FAMILY, SUPPORT and SUPPORT_JOINT in the type of a targetMedia item for FOLDER, CARRIER and CARRIER_JOINT. The field base is also still accepted for targetBase: do not send both, because the last one in the body is used. None of them is ever returned. Use the current names.

Errors​

errorMessage is meant for people and may be in the user's language. Base your error handling on errorCode.

StatuserrorCodeWhen
400AE_ERR_401tableType is missing or is not REACH_TABLE, REACH_DUPLICATION or REACH_TREND, or another enumerated field, such as dataType or the id of a dimension, has an invalid value. The message lists the valid values.
400AE_ERR_400decimals is negative, or an extraParams switch has an invalid value. weeks or weight of the table in a REACH_DUPLICATION or REACH_TREND, or a week or a weighting the survey does not have. A value of the wrong JSON type; the message names the field. 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.
400AE_ERR_402(REACH_TREND) A statistic outside the catalog of its axis.
400AE_ERR_405target or targetBase has neither a non-blank id nor a non-blank filterTgl.
400TG_ERR_113target or targetBase has an id that does not identify a saved target. It applies to every tableType, REACH_TREND included.
400TGL_ERR_101A filterTgl of target or targetBase uses a variable or category that the survey does not have.
400AE_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.
400AE_ERR_404, AE_ERR_409 to AE_ERR_414, AE_ERR_416Malformed dimensions or axes, including a field that an object does not accept (AE_ERR_411), also in a survey wave or its weight; see POST /api/v2/table/{surveyCode}.
400RC_ERR_100The survey does not support Reach. In a REACH_TREND, the API checks the survey of the path before calculating.
400RC_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).
400RC_ERR_108targetMedia includes carriers that the survey does not have.
400SP_ERR_101(REACH_TABLE, REACH_DUPLICATION) A carrier of a CARRIERS axis does not exist in the survey.
400RD_ERR_100REACH_DUPLICATION without a second CARRIERS axis.
400T_ERR_104No statistics were requested.
400T_ERR_106(REACH_TABLE, REACH_DUPLICATION) A statistic id that the calculation engine does not know.
400EV_ERR_108REACH_TABLE without carriers.
400TR_ERR_105(REACH_TREND) No survey wave is valid by availability, weeks or weighting.
400TR_ERR_106(REACH_TREND) trendCategoriesMode is not a valid value.
400TR_ERR_109(REACH_TREND) No survey wave is left after checking the variables of the table and the Reach checks of each wave.
400SO_ERR_201The survey is disabled or being loaded.
401E401The X-API-Key header is missing or empty.
401SO_ERR_203The survey does not exist or is not in your profile.
403AE_ERR_408The user does not have the Reach module.
422TGL_INVALIDA TGL expression of the request cannot be used: it does not parse, or it uses a variable without a category or a condition.
500GEN_ERR_500Unexpected error.

Errors raised by the calculation engine keep their own errorCode, with an errorMessage in the language of the API key's user.

Request​

Responses​

The calculated Reach table: the axes in dimensions and the values in matrixList.