Skip to main content

List available statistics

GET 

/api/v2/statistics

Returns the catalog of statistics you can request for a given table type.

Use each id in the STATISTICS axis of POST /api/v2/table/{surveyCode} (and its /html variant), or in the statistics list of POST /api/v2/survey/{surveyCode}/ranking and POST /api/v2/survey/{surveyCode}/evaluation.

How the catalog is built​

  • It depends on the table type, not on the survey: no surveyCode is needed, and the same ids apply to every survey. When tableType is omitted, TABULATION is assumed.
  • TABULATION returns audience statistics (for example wTotal, ColPercentWeighted, Sample). RANKING, EVALUATION, BREAKDOWN_CARRIERS and DUPLICATIONS return media statistics (for example COVER, GRP, OTS).
  • TREND returns the ids of the DIFFERENCES axis of a trend table: the differences between survey waves (for example TrendTotal, AbsPrev, PrcPrev). The audience statistics of its STATISTICS axis come with tableType=TREND&axis=STATISTICS.
  • The list follows the caller's TOM preferences: statistics the user has disabled are left out, and the order is the user's configured order. Two users can get different lists.
  • The preferences filter only this list. A ranking or an evaluation also accepts the statistics of its table type that the list leaves out, for example COVER and COVER_PERCENT, as used in the examples of those operations.
  • label and description come in the user's language. Use id as the identifier.
  • Reach statistics (REACH_TABLE, REACH_DUPLICATION, REACH_TREND) depend on the survey and are not listed here: get them from GET /api/v2/survey/{surveyCode}/reach-capabilities, which also lists the differences of a REACH_TREND. REACH_TREND is not a tableType of this operation.

The axis parameter​

A trend table has two axes of statistics. axis chooses the one whose statistics are listed:

axistableTypeList
Not sentAnyThe list of tableType. For TREND, the differences.
STATISTICSTRENDThe statistics of the STATISTICS axis of a trend: the ones of TABULATION without the row and column t-tests (TestTRow, TestTColumn).
STATISTICSAny otherThe list of tableType, the same as without axis.
DIFFERENCESTRENDThe differences, the same as without axis.
DIFFERENCESAny otherRejected with 400 (AE_ERR_400), without reading the catalog.

Every id of the list can be sent in the axis it was listed for.

Ids​

  • The id of a statistic is part of the contract. The ids of each table type are fixed: an id that exists today keeps its name and its meaning. New statistics can be added over time, so do not fail on an id you do not know.
  • Ids are case-sensitive and some mix cases (wTotal, COVER_PERCENT): send them exactly as listed.
  • A ranking adds a column PLAN_n to its result for each plan you define with insertions: PLAN_1 is the first plan, PLAN_2 the second, and so on. They appear only in the response and repeat the insertions of each carrier: do not send them in statistics (a ranking answers 400 AE_ERR_402). The figures of each plan as a whole are in POST /api/v2/survey/{surveyCode}/evaluation, in the row of the plan (type: MEDIA_PLAN).
  • A label or description that looks like a name between question marks (for example ?KEY?) means that the text has no translation for the user's language yet. Use the id and ignore that text.

Access​

TABULATION requires the Tabulation module. Every other table type requires the Study module, TREND also with axis=STATISTICS.

Errors​

StatuserrorCodeWhen
400AE_ERR_400axis is DIFFERENCES and tableType is not TREND.
400AE_ERR_401tableType or axis is not one of the accepted values. Values are case-sensitive.
401E401The X-API-Key header is missing or empty.
403AE_ERR_408The module required by tableType is not enabled for the user, the user's modules could not be resolved, or the key does not identify a TOM user.
500GEN_ERR_500Unexpected error.

Request​

Responses​

Statistics available for the requested table type, in the user's configured order.