Skip to main content

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​

ValueWhere to get it
workspaceIdid in GET /api/v2/workspaces
elementIdid of an entry of tabulations in GET /api/v2/workspace/{workspaceId}
surveyCodesurveyCode 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:

  • ROWS and COLUMNS give the row and column headers of every slice.
  • PLANES holds the remaining axes, including the statistics axis. Each combination of one item per PLANES axis 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 with actual: true in the combinations operation). With sliceId, you get that slice.
  • matrixList contains exactly one matrix: the returned slice. Its items identify the slice, with one entry per PLANES axis (axis is the axis id).
  • In dimensions, ROWS and COLUMNS list every visible item; PLANES lists 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).

  • combinations is the number of slices.
  • indexCombination is the position of the returned slice in the list returned by the combinations operation, starting at 1. It is reliable only when you pass sliceId: without it, it always reports the first slice.
  • selfTableLink, nextTableLink and previousTableLink reference the current, next and previous slice; nextTableLink is omitted on the last slice and previousTableLink on the first. Do not call them as they are: their last path segment is a sliceId, which you pass in the sliceId query 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.

StatuserrorCodeWhen
400DB_ERR_106The element cannot be loaded, for example an unknown elementId or workspaceId.
400TB_ERR_118, TB_ERR_119sliceId does not match the tabulation: wrong number of parts, or a part that points to an item that does not exist.
400TB_ERR_104No variable of the tabulation is valid in surveyCode.
400SO_ERR_201The survey is disabled or being loaded.
401E401The X-API-Key header is missing or empty.
401SO_ERR_203The survey is not in your profile or does not exist.
500GEN_ERR_500Unexpected error.

Request​

Responses​

The requested slice of the tabulation, with its structure and navigation data.