Get the Reach capabilities of a survey
GET/api/v2/survey/:surveyCode/reach-capabilities
Returns what a survey offers for Reach: the statistics you can request in each Reach mode, the differences of a Reach trend and the diary edges you can break the result down by or filter on.
Every statistic id, edge name and value code that you send to POST /api/v2/reach/{surveyCode} comes from this response.
Before you call it
- Choose a survey with
availableReach: trueinGET /api/v2/users/surveys. Reach works only on surveys built on a consumption diary; any other survey is rejected withRC_ERR_100. - The user behind the API key needs the Reach module.
Statistics
statistics holds the statistics of the STATISTICS axis of each 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. Each survey gets its own list, filtered by its diary type and the data it holds. label and description come in the language of the API key's user. The response also carries a code in each statistic and difference, which repeats its id: ignore it and use id.
- 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 returns400(AE_ERR_402) before calculating. An id of the list that the survey does not offer is left out, as inREACH_TABLE.
Differences
differences holds the statistics of the DIFFERENCES axis of each mode that has one, keyed REACH_TREND: 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. label and description come in the language of the user; when they cannot be read, label repeats the id. The Reach module is enough to read them.
Diary edges
diaryEdges lists the dimensions of the diary, such as the day of the week, the device or the time of day. The title of an edge is the survey's own text and is not translated. axisType tells you how to use each edge:
CUSTOM_DIARY_EDGE: the edge lists itsvalues. Break the result down by it with aCUSTOM_DIARY_EDGEaxis:edgeis the edgenameanditemsare valuecodes, sent as strings. A value withcombinesis a group of the codes it lists (for example, Weekend groups Saturday and Sunday).TIME_DIARY_EDGE: the edge has no list of values; it describes the time of day throughtime. Break the result down by time slots with aTIME_DIARY_EDGEaxis, using astepfromtime.allowedStepsRangesor, whentime.supportsExplicitRangesistrue, explicitHH:mmranges.time.defaultStartis the time at which the diary day starts.
An edge that has a filter can also restrict the whole calculation: send it in diaryFilters with the edge name and the value codes to keep. filter.values holds the default selection of the edge. Use the edges without filter as axes.
Caching
The catalog belongs to the survey and can change when the survey is reloaded. Read it for each survey you work with: the ids of the statistics do not change their name, but a survey offers only some of them, and the value codes belong to the survey.
Errors
| Status | errorCode | When |
|---|---|---|
| 400 | RC_ERR_100 | The survey does not support Reach. |
| 400 | SO_ERR_201 | The survey is temporarily unavailable (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. |
| 500 | GEN_ERR_500 | Unexpected error. |
Request
Responses
- 200
- 400
- 401
- 403
- 500
The statistics of each Reach mode, the differences of a Reach trend and the diary edges of the survey.
The survey does not support Reach (RC_ERR_100), or it is temporarily unavailable because it is disabled or being loaded (SO_ERR_201).
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).
Unexpected error.