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
- Check that the survey has
availableReach: trueinGET /api/v2/users/surveys. - Read
GET /api/v2/survey/{surveyCode}/reach-capabilitiesfor the statistic ids of each mode, the differences of aREACH_TRENDand the diary edge names and value codes. - Take carrier ids from
GET /api/v2/survey/{surveyCode}/carriers. - 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 aCARRIERSaxis (usuallyROWS) and the statistics in aSTATISTICSaxis (usuallyCOLUMNS). AddCUSTOM_DIARY_EDGE,TIME_DIARY_EDGEorVARIABLESaxes to break the result down.REACH_DUPLICATION: audience overlap between carriers. Put carriers in twoCARRIERSaxes, inROWSandCOLUMNS, so that each cell is a pair, and the statistics inPLANES.REACH_TREND: the statistics of aREACH_TABLEcompared across survey waves. It takes the axes of aREACH_TABLE(carriers, statistics and, if you want, variables and diary edge axes) plus aSOURCESaxis with the survey waves and aDIFFERENCESaxis 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
SOURCESaxis, aDIFFERENCESaxis and aCARRIERSaxis. Without one of them, the request is rejected withAE_ERR_412, naming the type of axis, before calculating. TheCARRIERSaxis goes inROWSorCOLUMNS: inPLANESthe request is rejected withAE_ERR_410. - Statistics. The
STATISTICSaxis takes the statistics of aREACH_TABLE(statistics.REACH_TRENDofreach-capabilities) and theDIFFERENCESaxis the differences of a trend (differences.REACH_TREND). Any other id is rejected withAE_ERR_402, naming the ids, before calculating. An id of the catalog that the survey does not offer is left out, as in aREACH_TABLE. - Survey waves. Each item of the
SOURCESaxis is a survey wave withidand, optionally,selected,weeksandweight, with the rules of aTRENDtable (seePOST /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 withoutweightgets no weighting.weeksandweightat the top level of the body are rejected withAE_ERR_400. - 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. To get the figures of a saved element, send it to itssurveyCode. - A survey of the path without Reach is rejected with
RC_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, as in aREACH_TABLE. - 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. 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 anERRORdiagnostic, and the response is200with the whole population, as in aTRENDtable. Anidthat does not identify a saved target returns400(TG_ERR_113), as in aREACH_TABLE, while aTRENDtable discards it with a diagnostic. AfilterTglwith a variable that the survey of the path does not have is rejected withTGL_ERR_101, also as in aTRENDtable.diagnostics.levelis thenERROR. A target that does not resolve in another wave leaves only that wave without values. - Carriers. A
CARRIER_JOINTis calculated in each survey wave that has all its carriers, with the figures of aREACH_TABLEof that wave. A carrier that no survey wave has comes without values and without a diagnostic: check the ids withGET /api/v2/survey/{surveyCode}/carriers. - Categories.
extraParams.trendCategoriesModeapplies as in aTRENDtable; an invalid value returnsTR_ERR_106. - Response. Shaped like the response of a
TRENDtable: theSOURCESandDIFFERENCESaxes come indimensions, and each survey wave carries itsweeksandweightwhen it had them. Carriers and axes come with their labels, as in aREACH_TABLE.
Diagnostics of a survey wave, in a 200 response:
| errorCode | When |
|---|---|
TR_ERR_107 | The 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_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. |
Diary edge axes
CUSTOM_DIARY_EDGE:edgeis the edgenameanditemsare valuecodes, sent as numeric strings (for example"1").TIME_DIARY_EDGE: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 thestepfromtime.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 targetidor an inline TGL expression infilterTgl; with both,filterTglwins. Atargetwith neither a non-blankidnor a non-blankfilterTglis rejected withAE_ERR_405(HTTP 400).targetBase: the population base. It fixes the reference universe of the percentages in the result. Send a saved targetidor an inline TGL expression infilterTgl; with both,filterTglwins. AtargetBasewith neither a non-blankidnor a non-blankfilterTglis rejected withAE_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 (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.
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
PLANESwith more than one marked"selected": true: one matrix per selected statistic, each identified by itsitems.
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.
| Status | errorCode | When |
|---|---|---|
| 400 | AE_ERR_401 | tableType 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. |
| 400 | AE_ERR_400 | decimals 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. |
| 400 | AE_ERR_402 | (REACH_TREND) A statistic 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. It applies to every tableType, REACH_TREND included. |
| 400 | TGL_ERR_101 | A filterTgl of target or targetBase 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 | Malformed 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}. |
| 400 | RC_ERR_100 | The survey does not support Reach. In a REACH_TREND, the API checks the survey of the path before calculating. |
| 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 | SP_ERR_101 | (REACH_TABLE, REACH_DUPLICATION) A carrier of a CARRIERS axis does not exist in the survey. |
| 400 | RD_ERR_100 | REACH_DUPLICATION without a second CARRIERS axis. |
| 400 | T_ERR_104 | No statistics were requested. |
| 400 | T_ERR_106 | (REACH_TABLE, REACH_DUPLICATION) A statistic id that the calculation engine does not know. |
| 400 | EV_ERR_108 | REACH_TABLE without carriers. |
| 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 | SO_ERR_201 | The survey is disabled or being loaded. |
| 401 | E401 | The X-API-Key header is missing or empty. |
| 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 TGL expression of the request cannot be used: it does not parse, or it uses a variable without a category or a condition. |
| 500 | GEN_ERR_500 | Unexpected 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
- 200
- 400
- 401
- 403
- 422
- 500
The calculated Reach table: the axes in dimensions and the values in matrixList.
The request is invalid or cannot be calculated on this survey. See the Errors table in the operation description for every errorCode. A variable of a VARIABLES axis that cannot be converted returns AE_ERR_412 (missing subtype, id or filterTgl) or AE_ERR_416 (unsupported combination); both locate the axis, dimension, variable, field and offending value (if any). RC_ERR_100: the survey does not support Reach. AE_ERR_401: tableType is missing or is not a Reach type. AE_ERR_405: target or targetBase has neither id nor filterTgl. AE_ERR_400 also covers weeks or weight sent with a table type that does not take them, a week or a weighting the survey does not have, and targetMedia or diaryFilters with a table type that is not Reach. AE_ERR_411 covers an unknown field in a survey wave of a SOURCES axis or in its weight, and AE_ERR_412 a weight without id. AE_ERR_404 covers more than one selected survey wave in a SOURCES axis in PLANES. A REACH_TREND without its SOURCES, DIFFERENCES or CARRIERS axis returns AE_ERR_412, a statistic outside the catalog of its axis returns AE_ERR_402, and a survey of the path without Reach returns RC_ERR_100, all before calculating. T_ERR_104 (no statistics) and T_ERR_106 (a statistic the engine does not know) are raised by the calculation engine. The calculation engine also returns TG_ERR_113 (a target or targetBase id that does not identify a saved target), TGL_ERR_101 (a TGL expression with a variable or category the survey does not have) and SP_ERR_101 (a carrier the survey does not have). A REACH_TREND also returns TR_ERR_105, TR_ERR_106 and TR_ERR_109 from the calculation engine, as a TREND table does; a discarded survey wave is a TR_ERR_107 diagnostic of a 200 response.
The X-API-Key header is missing or empty (E401), or the survey is not in the user's profile or does not exist (SO_ERR_203).
The application module this operation needs is not enabled for the user, or the user's modules could not be resolved (AE_ERR_408).
A TGL expression of the request cannot be used (TGL_INVALID): it does not parse, or it uses a variable without a category or condition. An unknown variable or category returns 400 TGL_ERR_101 instead.
Unexpected error.