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
surveyCodeis needed, and the same ids apply to every survey. WhentableTypeis omitted,TABULATIONis assumed. TABULATIONreturns audience statistics (for examplewTotal,ColPercentWeighted,Sample).RANKING,EVALUATION,BREAKDOWN_CARRIERSandDUPLICATIONSreturn media statistics (for exampleCOVER,GRP,OTS).TRENDreturns the ids of theDIFFERENCESaxis of a trend table: the differences between survey waves (for exampleTrendTotal,AbsPrev,PrcPrev). The audience statistics of itsSTATISTICSaxis come withtableType=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
COVERandCOVER_PERCENT, as used in the examples of those operations. labelanddescriptioncome in the user's language. Useidas the identifier.- Reach statistics (
REACH_TABLE,REACH_DUPLICATION,REACH_TREND) depend on the survey and are not listed here: get them fromGET /api/v2/survey/{surveyCode}/reach-capabilities, which also lists the differences of aREACH_TREND.REACH_TRENDis not atableTypeof this operation.
The axis parameter
A trend table has two axes of statistics. axis chooses the one whose statistics are listed:
axis | tableType | List |
|---|---|---|
| Not sent | Any | The list of tableType. For TREND, the differences. |
STATISTICS | TREND | The statistics of the STATISTICS axis of a trend: the ones of TABULATION without the row and column t-tests (TestTRow, TestTColumn). |
STATISTICS | Any other | The list of tableType, the same as without axis. |
DIFFERENCES | TREND | The differences, the same as without axis. |
DIFFERENCES | Any other | Rejected 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
idof 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_nto its result for each plan you define withinsertions:PLAN_1is the first plan,PLAN_2the second, and so on. They appear only in the response and repeat the insertions of each carrier: do not send them instatistics(a ranking answers400AE_ERR_402). The figures of each plan as a whole are inPOST /api/v2/survey/{surveyCode}/evaluation, in the row of the plan (type: MEDIA_PLAN). - A
labelordescriptionthat looks like a name between question marks (for example?KEY?) means that the text has no translation for the user's language yet. Use theidand ignore that text.
Access
TABULATION requires the Tabulation module. Every other table type requires the Study module, TREND also with axis=STATISTICS.
Errors
| Status | errorCode | When |
|---|---|---|
| 400 | AE_ERR_400 | axis is DIFFERENCES and tableType is not TREND. |
| 400 | AE_ERR_401 | tableType or axis is not one of the accepted values. Values are case-sensitive. |
| 401 | E401 | The X-API-Key header is missing or empty. |
| 403 | AE_ERR_408 | The 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. |
| 500 | GEN_ERR_500 | Unexpected error. |
Request
Responses
- 200
- 400
- 401
- 403
- 500
Statistics available for the requested table type, in the user's configured order.
tableType or axis is not one of the accepted values (AE_ERR_401), or axis is DIFFERENCES with a tableType other than TREND (AE_ERR_400). Values are case-sensitive.
The X-API-Key header is missing or empty.
The module required by tableType (Tabulation for TABULATION, Study for the rest) is not enabled for the user, or the user's modules could not be resolved (AE_ERR_408). An API key that does not identify a TOM user also gets this response.
Unexpected error.