Retrieve detailed information for a specific tabulation.
GET/api/v1/workspace/:workspaceId/survey/:surveyCode/tabulation/:elementId
This method retrieves detailed data for a specific tabulation, which represents a three-dimensional data cube (a multivariate cross-tabulation). This element should be already created by the user in the platform.
A tabulation is structured by three main dimensions: ROWS, COLUMNS, and PLANES. These dimensions contain one or more axes (containers for variables or statistical elements). The full data cube represents the combination of all items across all axes in all three dimensions.
This endpoint performs two main actions:
- Returns the full metadata specification for the tabulation, detailing what is included in the ROWS, COLUMNS, and PLANES dimensions.
- Returns a specific slice (a 2D matrix) of the data cube. This slice is defined by including all items for the ROWS and COLUMNS dimensions, and a single, fixed combination of items for the PLANES dimension.
sliceId parameter allows user to specify plane combination to use. These Ids can be obtained from combinations endpoint.
Response Body Structure
The response contains two main sections: dimensions (the metadata) and matrix (the data slice).
Dimensions (Metadata)
The dimensions array explains how the tabulation is structured:
-
ROWS – Defines all row axes of the returned 2D table. Example items: Axe 1: TOTAL, SEX.D1 (Male), SEX.D2 (Female).
-
COLUMNS – Defines all column axes of the returned 2D table. Example items: Axe2: TOTAL, EDA1.D1 (14–19), ..., EDA1.D9 (75+).
-
PLANES – Defines the additional data layers, one of this layer will be provided in Matrix section. Example items: STATISTICS (e.g., Weighted Total wTotal), another variable axis (e.g., 3 for Marital Status ESTATOM).
Matrix Representation (Data Slice)
The matrix array holds the actual data. Since this endpoint returns a single 2D slice, the array will contain one object.
-
matrix[].items: This property explicitly defines the fixed combination of items from the PLANES dimension used to generate the data slice. Every value in the table corresponds to this combination.
-
matrix[].table: A two-dimensional array of numeric values. Each value is the result of a unique intersection point from the three dimensions.
Data Mapping and Traversal
The values in matrix[].table are ordered according to the items in the ROWS dimension (outer array) and COLUMNS dimension (inner array), fixed by the PLANES combination.
Consumers must traverse the table in the following order to correctly map data points back to the dimensions:
-
ROWS – (First Index [r]): The outer array index (row) corresponds to a specific item from the ROWS dimension.
-
COLUMNS - (Second Index [c]): The inner array index (column) corresponds to a specific item from the COLUMNS dimension.
-
PLANES (Fixed) - The value is always associated with the fixed plane combination defined in the matrix[].items property.
Example Mapping
This demonstrates how a cell value is mapped to the full 3D coordinates, using the example data where the PLANE is fixed as {STATISTICS: wTotal, 3: ESTATOM.D1 (Casado)}:
| Cell Index | Value | Corresponding Data Point |
|---|---|---|
| table[0][0] | 42623.77 | {ROW: TOTAL, COLUMN: TOTAL, PLANES: {STATISTICS: wTotal, 3: ESTATOM.D1} } |
| table[1][2] | 1358.40 | {ROW: SEX.D1 (Male), COLUMN: EDA1.D2 (20–24), PLANES: {STATISTICS: wTotal, 3: ESTATOM.D1}} |
| table[2][8] | 2892.27 | {ROW: SEX.D2 (Female), COLUMN: EDA1.D9 (75+), PLANES: {STATISTICS: wTotal, 3: ESTATOM.D1}} |
Plane navigation
The response also includes pagination over plane combinations:
-
combinations (integer): total number of available PLANES combinations (total possible slices).
-
indexCombination (integer): the index of the current slice in [0, combinations - 1].
-
selfTableLink: relative link to the current slice.
-
nextTableLink: relative link to the next slice (null if none).
-
previousTableLink: relative link to the previous slice (null if none).
All links return the same response structure with matrix updated for the corresponding plane combination.
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 500
Tabulation retrieved successfully.
Bad Request. The request parameters are invalid.
Unauthorized. Missing or invalid API key.
Forbidden. The API key does not grant access to workspaces.
Not Found. The requested resource was not found.
Internal Server Error. Unexpected error occurred while processing the request.