Get a saved tabulation
GET/api/v2/workspace/:workspaceId/survey/:surveyCode/tabulation/:elementId
Calculates a tabulation saved in a workspace and returns its structure together with one two-dimensional slice of its data.
Use it to read the tabulations that users build in the TOM web application. To calculate a table from your own definition, use POST /api/v2/table/{surveyCode}. To get the saved definition in a form you can edit and send again, use GET /api/v2/workspace/{workspaceId}/element/{elementId}.
Before you call it
| Value | Where to get it |
|---|---|
workspaceId | id in GET /api/v2/workspaces |
elementId | id of an entry of tabulations in GET /api/v2/workspace/{workspaceId} |
surveyCode | surveyCode of the same workspace |
sliceId (optional) | itemCombinations[].sliceId in GET /api/v2/workspace/{workspaceId}/survey/{surveyCode}/tabulation/{elementId}/combinations |
How a tabulation is organised
A tabulation is a data cube with three dimensions, each made of one or more axes:
ROWSandCOLUMNSgive the row and column headers of every slice.PLANESholds the remaining axes, including the statistics axis. Each combination of one item perPLANESaxis is a slice, for example the statistic Weighted total with the marital status Married.
Behaviour
- The figures are computed from the current saved definition and survey data. The call is read-only and does not change the tabulation.
- Without
sliceId, you get the slice saved as current in the tabulation (the combination withactual: truein the combinations operation). WithsliceId, you get that slice. matrixListcontains exactly one matrix: the returned slice. Itsitemsidentify the slice, with one entry perPLANESaxis (axisis the axis id).- In
dimensions,ROWSandCOLUMNSlist every visible item;PLANESlists only the items of the returned slice. To list all the slices, call the combinations operation. - Labels come in the language of the user.
Reading the matrix
matrixList[0].table[r][c] is the cell for the r-th item of ROWS and the c-th item of COLUMNS, in the order in which those items appear in dimensions. rowCount and columnCount give the size of the matrix. In a saved tabulation every cell is an object with the raw value and the formatted text shown in the TOM web application, in the user's locale, as in the example: read value for the number.
In the example response below, table[0][0] is the value for SEX.D1 (Male) by EDA1.D1 (14 to 19), table[0][1] is SEX.D1 by EDA1.D2 (20 to 24) and table[1][7] is SEX.D2 (Female) by EDA1.D8 (75 and over), all of them for the slice with the statistic wTotal and ESTATOM.D1 (Married).
Navigating slices
combinationsis the number of slices.indexCombinationis the position of the returned slice in the list returned by the combinations operation, starting at 1. It is reliable only when you passsliceId: without it, it always reports the first slice.selfTableLink,nextTableLinkandpreviousTableLinkreference the current, next and previous slice;nextTableLinkis omitted on the last slice andpreviousTableLinkon the first. Do not call them as they are: their last path segment is asliceId, which you pass in thesliceIdquery parameter of this operation.
Tip: to iterate over the slices, call the combinations operation once and then pass each sliceId explicitly.
Errors
errorMessage is meant for people and may be in the user's language. Base your error handling on errorCode.
| Status | errorCode | When |
|---|---|---|
| 400 | DB_ERR_106 | The element cannot be loaded, for example an unknown elementId or workspaceId. |
| 400 | TB_ERR_118, TB_ERR_119 | sliceId does not match the tabulation: wrong number of parts, or a part that points to an item that does not exist. |
| 400 | TB_ERR_104 | No variable of the tabulation is valid in surveyCode. |
| 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 is not in your profile or does not exist. |
| 500 | GEN_ERR_500 | Unexpected error. |
Request
Responses
- 200
- 400
- 401
- 500
The requested slice of the tabulation, with its structure and navigation data.
The tabulation cannot be calculated: the element cannot be loaded (DB_ERR_106), sliceId does not match the tabulation (TB_ERR_118 or TB_ERR_119), no variable of the tabulation is valid in surveyCode (TB_ERR_104), or the survey is disabled or being loaded (SO_ERR_201). errorCode carries the code of the calculation engine.
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).
Unexpected error.