Skip to main content

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: true in GET /api/v2/users/surveys. Reach works only on surveys built on a consumption diary; any other survey is rejected with RC_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_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​

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 its values. Break the result down by it with a CUSTOM_DIARY_EDGE axis: edge is the edge name and items are value codes, sent as strings. A value with combines is 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 through time. Break the result down by time slots with a TIME_DIARY_EDGE axis, using a step from time.allowedStepsRanges or, when time.supportsExplicitRanges is true, explicit HH:mm ranges. time.defaultStart is 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​

StatuserrorCodeWhen
400RC_ERR_100The survey does not support Reach.
400SO_ERR_201The survey is temporarily unavailable (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.
500GEN_ERR_500Unexpected error.

Request​

Responses​

The statistics of each Reach mode, the differences of a Reach trend and the diary edges of the survey.