tom-external-api API v3.10.0-SNAPSHOT

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Authentication

API Key (X-API-Key)
- Parameter Name: X-API-Key, in: header. Authentication

This API uses API Key Authentication that should have been provided.

You must include your API key in the request header:

Header Name: X-API-Key

Location: header

Description: A valid API key is required to authenticate and authorize all requests.

1. Surveys

Retrieve surveys

Code samples

# You can also use wget
curl -X GET /api/v1/users/surveys \
  -H 'Accept: application/json' \
  -H 'X-API-Key: odec'

import requests
headers = {
  'Accept': 'application/json',
  'X-API-Key': 'odec'
}

r = requests.get('/api/v1/users/surveys', headers = headers)

print(r.json())

URL obj = new URL("/api/v1/users/surveys");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /api/v1/users/surveys

This endpoint returns a list of all available databases or surveys for the authenticated user.

Use it to discover which surveys you can access.

Example responses

List of surveys retrieved successfully.

[
  {
    "code": "SURVEY MARKET AND MEDIA 2030",
    "description": "General overview of market and media of the world",
    "creationDate": "2023-03-01T16:03:27.592+00:00",
    "updateDate": "2023-03-01T16:03:27.592+00:00"
  }
]

Bad Request. The request parameters are invalid.

{
  "status": "Bad Request",
  "errorCode": "400",
  "errorMessage": "Invalid request parameters.",
  "statusCode": "400"
}

Unauthorized. Missing or invalid API key.

{
  "status": "Unauthorized",
  "errorCode": "401",
  "errorMessage": "Missing or invalid API key.",
  "statusCode": "401"
}

Forbidden. The API key does not grant access to workspaces.

{
  "status": "Forbidden",
  "errorCode": "403",
  "errorMessage": "Access denied.",
  "statusCode": "403"
}

Not Found. No workspaces found.

{
  "status": "Not Found",
  "errorCode": "404",
  "errorMessage": "Not Found",
  "statusCode": "404"
}

Internal Server Error. Unexpected error occurred while processing the request.

{
  "status": "Internal Server Error",
  "errorCode": "500",
  "errorMessage": "Unexpected server error.",
  "statusCode": "500"
}

Responses

Status	Meaning	Description	Schema
200	OK	List of surveys retrieved successfully.	Survey
400	Bad Request	Bad Request. The request parameters are invalid.	Problem
401	Unauthorized	Unauthorized. Missing or invalid API key.	Problem
403	Forbidden	Forbidden. The API key does not grant access to workspaces.	Problem
404	Not Found	Not Found. No workspaces found.	Problem
500	Internal Server Error	Internal Server Error. Unexpected error occurred while processing the request.	Problem

2. Workspaces

Retrieve workspace by ID

Code samples

# You can also use wget
curl -X GET /api/v1/workspace/{workspaceId} \
  -H 'Accept: application/json' \
  -H 'X-API-Key: odec'

import requests
headers = {
  'Accept': 'application/json',
  'X-API-Key': 'odec'
}

r = requests.get('/api/v1/workspace/{workspaceId}', headers = headers)

print(r.json())

URL obj = new URL("/api/v1/workspace/{workspaceId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /api/v1/workspace/{workspaceId}

Fetch detailed information for a specific workspace identified by its workspaceId.

Parameters

Name	In	Type	Required	Description
workspaceId	path	string	true	Identifier unique workspace

Example responses

Workspace retrieved successfully.

{
  "id": "F780D8B99A1E513EE053CD6710AC7753",
  "name": "New workspace",
  "surveyCode": "APP_DEMO_2025",
  "surveyDescription": "Demonstration application for testing",
  "creationDate": "2023-03-01T16:03:27.592+00:00",
  "tabulations": [
    {
      "id": "F780D8B99A1E513EE053CD6710AC7753",
      "name": "New tabulation",
      "creationDate": "2023-03-01T16:03:27.592+00:00",
      "updateDate": "2023-03-01T16:03:27.592+00:00"
    }
  ],
  "targets": [
    {
      "id": "F780D8B99A1E513EE053CD6710AC7753",
      "name": "New target",
      "creationDate": "2023-03-01T16:03:27.592+00:00",
      "updateDate": "2023-03-01T16:03:27.592+00:00"
    }
  ],
  "userVars": [
    {
      "id": "F780D8B99A1E513EE053CD6710AC7753",
      "name": "New user variable",
      "creationDate": "2023-03-01T16:03:27.592+00:00",
      "updateDate": "2023-03-01T16:03:27.592+00:00"
    }
  ],
  "surveys": [
    {
      "code": "APP_DEMO_2025",
      "description": "Demonstration application for testing",
      "creationDate": "2023-03-01T16:03:27.592+00:00",
      "updateDate": "2023-03-01T16:03:27.592+00:00"
    }
  ]
}

Bad Request. The request parameters are invalid.

{
  "status": "Bad Request",
  "errorCode": "400",
  "errorMessage": "Invalid request parameters.",
  "statusCode": "400"
}

Unauthorized. Missing or invalid API key.

{
  "status": "Unauthorized",
  "errorCode": "401",
  "errorMessage": "Missing or invalid API key.",
  "statusCode": "401"
}

Forbidden. The API key does not grant access to workspaces.

{
  "status": "Forbidden",
  "errorCode": "403",
  "errorMessage": "Access denied.",
  "statusCode": "403"
}

Not Found. No workspaces found.

{
  "status": "Not Found",
  "errorCode": "404",
  "errorMessage": "Not Found",
  "statusCode": "404"
}

Internal Server Error. Unexpected error occurred while processing the request.

{
  "status": "Internal Server Error",
  "errorCode": "500",
  "errorMessage": "Unexpected server error.",
  "statusCode": "500"
}

Responses

Status	Meaning	Description	Schema
200	OK	Workspace retrieved successfully.	WorkspaceDetail
400	Bad Request	Bad Request. The request parameters are invalid.	Problem
401	Unauthorized	Unauthorized. Missing or invalid API key.	Problem
403	Forbidden	Forbidden. The API key does not grant access to workspaces.	Problem
404	Not Found	Not Found. No workspaces found.	Problem
500	Internal Server Error	Internal Server Error. Unexpected error occurred while processing the request.	Problem

Retrieve workspaces

Code samples

# You can also use wget
curl -X GET /api/v1/workspaces \
  -H 'Accept: application/json' \
  -H 'X-API-Key: odec'

import requests
headers = {
  'Accept': 'application/json',
  'X-API-Key': 'odec'
}

r = requests.get('/api/v1/workspaces', headers = headers)

print(r.json())

URL obj = new URL("/api/v1/workspaces");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /api/v1/workspaces

Fetches a list of all available workspaces including metadata.

Example responses

Workspaces retrieved successfully.

[
  {
    "id": "F780D8B99A1E513EE053CD6710AC7753",
    "name": "New workspace",
    "surveyCode": "APP_DEMO_2025",
    "surveyDescription": "Demonstration application for testing",
    "creationDate": "2023-03-01T16:03:27.592+00:00"
  }
]

Bad Request. The request parameters are invalid.

{
  "status": "Bad Request",
  "errorCode": "400",
  "errorMessage": "Invalid request parameters.",
  "statusCode": "400"
}

Unauthorized. Missing or invalid API key.

{
  "status": "Unauthorized",
  "errorCode": "401",
  "errorMessage": "Missing or invalid API key.",
  "statusCode": "401"
}

Forbidden. The API key does not grant access to workspaces.

{
  "status": "Forbidden",
  "errorCode": "403",
  "errorMessage": "Access denied.",
  "statusCode": "403"
}

Not Found. No workspaces found.

{
  "status": "Not Found",
  "errorCode": "404",
  "errorMessage": "Not Found",
  "statusCode": "404"
}

Internal Server Error. Unexpected error occurred while processing the request.

{
  "status": "Internal Server Error",
  "errorCode": "500",
  "errorMessage": "Unexpected server error.",
  "statusCode": "500"
}

Responses

Status	Meaning	Description	Schema
200	OK	Workspaces retrieved successfully.	Workspace
400	Bad Request	Bad Request. The request parameters are invalid.	Problem
401	Unauthorized	Unauthorized. Missing or invalid API key.	Problem
403	Forbidden	Forbidden. The API key does not grant access to workspaces.	Problem
404	Not Found	Not Found. No workspaces found.	Problem
500	Internal Server Error	Internal Server Error. Unexpected error occurred while processing the request.	Problem

3. Variables

Retrieve variables by survey code

Code samples

# You can also use wget
curl -X GET /api/v1/survey/{surveyCode}/variables \
  -H 'Accept: application/json' \
  -H 'X-API-Key: odec'

import requests
headers = {
  'Accept': 'application/json',
  'X-API-Key': 'odec'
}

r = requests.get('/api/v1/survey/{surveyCode}/variables', headers = headers)

print(r.json())

URL obj = new URL("/api/v1/survey/{surveyCode}/variables");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /api/v1/survey/{surveyCode}/variables

Returns the list of variables that belong to the survey identified by {surveyCode}. Useful for building tabulation axes (ROWS/COLUMNS/PLANES) and resolving codes to labels.

Parameters

Name	In	Type	Required	Description
surveyCode	path	string	true	Identifier unique surveyCode

Example responses

Variables retrieved successfully.

[
  {
    "id": "F780D8B99A1E513EE053CD6710AC7753",
    "code": "VARIABLE1",
    "label": "Variable number 1 example",
    "categories": [
      {
        "id": "F780D8B99A1E513EE053CD6710AC7753",
        "code": "CATEGORY 1",
        "label": "Variable CATEGORY EXAMPLE 1"
      },
      {
        "id": "F780D8B99A1E513EE053CD6710AC7753",
        "code": "CATEGORY 2",
        "label": "Variable CATEGORY EXAMPLE 2"
      }
    ]
  }
]

Bad Request. The request parameters are invalid.

{
  "status": "Bad Request",
  "errorCode": "400",
  "errorMessage": "Invalid request parameters.",
  "statusCode": "400"
}

Unauthorized. Missing or invalid API key.

{
  "status": "Unauthorized",
  "errorCode": "401",
  "errorMessage": "Missing or invalid API key.",
  "statusCode": "401"
}

Forbidden. The API key does not grant access to workspaces.

{
  "status": "Forbidden",
  "errorCode": "403",
  "errorMessage": "Access denied.",
  "statusCode": "403"
}

Not Found. No workspaces found.

{
  "status": "Not Found",
  "errorCode": "404",
  "errorMessage": "Not Found",
  "statusCode": "404"
}

Internal Server Error. Unexpected error occurred while processing the request.

{
  "status": "Internal Server Error",
  "errorCode": "500",
  "errorMessage": "Unexpected server error.",
  "statusCode": "500"
}

Responses

Status	Meaning	Description	Schema
200	OK	Variables retrieved successfully.	Category
400	Bad Request	Bad Request. The request parameters are invalid.	Problem
401	Unauthorized	Unauthorized. Missing or invalid API key.	Problem
403	Forbidden	Forbidden. The API key does not grant access to workspaces.	Problem
404	Not Found	Not Found. No workspaces found.	Problem
500	Internal Server Error	Internal Server Error. Unexpected error occurred while processing the request.	Problem

4. Tabulation

Retrieve detailed information for a specific tabulation.

Code samples

# You can also use wget
curl -X GET /api/v1/workspace/{workspaceId}/survey/{surveyCode}/tabulation/{elementId} \
  -H 'Accept: application/json' \
  -H 'X-API-Key: odec'

import requests
headers = {
  'Accept': 'application/json',
  'X-API-Key': 'odec'
}

r = requests.get('/api/v1/workspace/{workspaceId}/survey/{surveyCode}/tabulation/{elementId}', headers = headers)

print(r.json())

URL obj = new URL("/api/v1/workspace/{workspaceId}/survey/{surveyCode}/tabulation/{elementId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

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.

Parameters

Name	In	Type	Required	Description
elementId	path	string	true	Identifier unique element
surveyCode	path	string	true	Identifier unique surveyCode
workspaceId	path	string	true	Identifier unique workspace
sliceId	query	string	false	Identifier unique combination

Example responses

Tabulation retrieved successfully.

{
  "dimensions": [
    {
      "id": "ROWS",
      "axis": [
        {
          "id": "1",
          "label": "Eje:1",
          "items": [
            {
              "id": "TOTAL",
              "label": "TOTAL"
            },
            {
              "id": "SEX",
              "label": "SEXO",
              "items": [
                {
                  "id": "D1",
                  "label": "Hombre"
                },
                {
                  "id": "D2",
                  "label": "Mujer"
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "id": "COLUMNS",
      "axis": [
        {
          "id": "2",
          "label": "Eje:2",
          "items": [
            {
              "id": "TOTAL",
              "label": "TOTAL"
            },
            {
              "id": "EDA1",
              "label": "EDAD 1",
              "items": [
                {
                  "id": "D1",
                  "label": "14 a 19"
                },
                {
                  "id": "D2",
                  "label": "20 a 24"
                },
                {
                  "id": "D3",
                  "label": "25 a 34"
                },
                {
                  "id": "D4",
                  "label": "35 a 44"
                },
                {
                  "id": "D5",
                  "label": "45 a 54"
                },
                {
                  "id": "D6",
                  "label": "55 a 64"
                },
                {
                  "id": "D8",
                  "label": "65 a 74"
                },
                {
                  "id": "D9",
                  "label": "75 y más"
                }
              ]
            }
          ],
          "split": false
        }
      ],
      "hidden": false
    },
    {
      "id": "PLANES",
      "axis": [
        {
          "id": "STATISTICS",
          "label": "Estadísticos",
          "items": [
            {
              "id": "wTotal",
              "label": "Individuos Pond."
            }
          ]
        },
        {
          "id": "3",
          "label": "Eje:3",
          "items": [
            {
              "id": "TOTAL",
              "label": "TOTAL"
            },
            {
              "id": "ESTATOM",
              "label": "ESTADO CIVIL",
              "items": [
                {
                  "id": "D1",
                  "label": "Casado"
                },
                {
                  "id": "D2",
                  "label": "Soltero"
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "matrix": [
    {
      "items": [
        {
          "axis": "STATISTICS",
          "item": {
            "id": "wTotal",
            "label": "Individuos Pond."
          }
        },
        {
          "axis": "3",
          "item": {
            "id": "D1",
            "label": "Casado"
          }
        }
      ],
      "table": [
        [
          42623.77699999835,
          3169.958927300932,
          2636.522389546276,
          5476.1397787241285,
          6569.577827830844,
          7951.506066845767,
          6912.5561608110165,
          5051.036464171545,
          4856.479384767773
        ],
        [
          20762.887955152037,
          1636.0581590307802,
          1358.4049191424385,
          2783.5690272470083,
          3281.5304202101274,
          3989.1776302087283,
          3378.19842346723,
          2371.74645249328,
          1964.2029233525413
        ],
        [
          21860.88904484614,
          1533.900768270152,
          1278.1174704038376,
          2692.5707514771216,
          3288.0474076207133,
          3962.328436637037,
          3534.3577373437843,
          2679.2900116782657,
          2892.276461415232
        ]
      ],
      "columnCount": 9,
      "rowCount": 3
    }
  ],
  "combinations": 102,
  "indexCombination": 2,
  "selfTableLink": "/workspace/{workspaceId}/survey/{surveyCode}/tabulation/{elementId}/mWyymQ20-ZX37DPz1-XKMr4Pz9",
  "nextTableLink": "/workspace/{workspaceId}/survey/{surveyCode}/tabulation/{elementId}/mWyymQ20-ZX57DPz4-XKMr4Pz9",
  "previousTableLink": "/workspace/{workspaceId}/survey/{surveyCode}/tabulation/{elementId}/mWyymQ20-ZX52DPz4-XKMr1Pz9"
}

Bad Request. The request parameters are invalid.

{
  "status": "Bad Request",
  "errorCode": "400",
  "errorMessage": "Invalid request parameters.",
  "statusCode": "400"
}

Unauthorized. Missing or invalid API key.

{
  "status": "Unauthorized",
  "errorCode": "401",
  "errorMessage": "Missing or invalid API key.",
  "statusCode": "401"
}

Forbidden. The API key does not grant access to workspaces.

{
  "status": "Forbidden",
  "errorCode": "403",
  "errorMessage": "Access denied.",
  "statusCode": "403"
}

Not Found. No workspaces found.

{
  "status": "Not Found",
  "errorCode": "404",
  "errorMessage": "Not Found",
  "statusCode": "404"
}

Internal Server Error. Unexpected error occurred while processing the request.

{
  "status": "Internal Server Error",
  "errorCode": "500",
  "errorMessage": "Unexpected server error.",
  "statusCode": "500"
}

Responses

Status	Meaning	Description	Schema
200	OK	Tabulation retrieved successfully.	Table
400	Bad Request	Bad Request. The request parameters are invalid.	Problem
401	Unauthorized	Unauthorized. Missing or invalid API key.	Problem
403	Forbidden	Forbidden. The API key does not grant access to workspaces.	Problem
404	Not Found	Not Found. No workspaces found.	Problem
500	Internal Server Error	Internal Server Error. Unexpected error occurred while processing the request.	Problem

Retrieve Plane Combinations for a Tabulation

Code samples

# You can also use wget
curl -X GET /api/v1/workspace/{workspaceId}/survey/{surveyCode}/tabulation/{elementId}/combinations \
  -H 'Accept: application/json' \
  -H 'X-API-Key: odec'

import requests
headers = {
  'Accept': 'application/json',
  'X-API-Key': 'odec'
}

r = requests.get('/api/v1/workspace/{workspaceId}/survey/{surveyCode}/tabulation/{elementId}/combinations', headers = headers)

print(r.json())

URL obj = new URL("/api/v1/workspace/{workspaceId}/survey/{surveyCode}/tabulation/{elementId}/combinations");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /api/v1/workspace/{workspaceId}/survey/{surveyCode}/tabulation/{elementId}/combinations

This method fetches the complete list of unique plane combinations (slices) that constitute the third dimension (PLANES) of a specific data cube. Each combination defines a unique 2D matrix slice that can be retrieved via the main tabulation endpoint, using the sliceId parameter.

Response Body

The response returns an object containing the total number of combinations and an array detailing each unique plane combination

Property	Type	Description
combinations	Integer	The total number of available 2D slices in the data cube. This is the product of all items across all axes in the PLANES dimension.
itemCombinations	Array	A list where each object specifies a unique combination of items from the PLANES axes.
itemCombinations[i].items	Array	The list of specific items (one per axis in the PLANES dimension) that define this 2D slice.
itemCombinations[i].items[j].axis	string	The ID of the axis (e.g., STATISTICS or 3) to which the item belongs.
itemCombinations[i].items[j].item	Object	The specific item object, including its id and label.
itemCombinations[i].sliceId	string	A unique identifier (sliceId) for this specific plane combination. This sliceId is used to request this exact slice in the main tabulation endpoint (GET /.../tabulation/{elementId}/{sliceId}).

Parameters

Name	In	Type	Required	Description
elementId	path	string	true	Identifier unique element
surveyCode	path	string	true	Identifier unique surveyCode
workspaceId	path	string	true	Identifier unique workspace

Example responses

Tabulation retrieved successfully.

{
  "combinations": 3,
  "itemCombinations": [
    {
      "items": [
        {
          "axis": "STATISTICS",
          "item": {
            "id": "wTotal",
            "label": "Individuos Pond."
          }
        },
        {
          "axis": "3",
          "item": {
            "id": "TOTAL",
            "label": "TOTAL"
          }
        }
      ],
      "sliceId": "mWyymQ20-ZX37DPz1-XKMr4Pz9"
    },
    {
      "items": [
        {
          "axis": "STATISTICS",
          "item": {
            "id": "wTotal",
            "label": "Individuos Pond."
          }
        },
        {
          "axis": "3",
          "item": {
            "id": "D1",
            "label": "Casado"
          }
        }
      ],
      "sliceId": "mWyymQ20-ZX57DPz4-XKMr1Pz9"
    },
    {
      "items": [
        {
          "axis": "STATISTICS",
          "item": {
            "id": "wTotal",
            "label": "Individuos Pond."
          }
        },
        {
          "axis": "3",
          "item": {
            "id": "D2",
            "label": "Soltero"
          }
        }
      ],
      "sliceId": "mWyymQ20-ZX57DPz4-XKMr2Pz9"
    }
  ]
}

Bad Request. The request parameters are invalid.

{
  "status": "Bad Request",
  "errorCode": "400",
  "errorMessage": "Invalid request parameters.",
  "statusCode": "400"
}

Unauthorized. Missing or invalid API key.

{
  "status": "Unauthorized",
  "errorCode": "401",
  "errorMessage": "Missing or invalid API key.",
  "statusCode": "401"
}

Forbidden. The API key does not grant access to workspaces.

{
  "status": "Forbidden",
  "errorCode": "403",
  "errorMessage": "Access denied.",
  "statusCode": "403"
}

Not Found. No workspaces found.

{
  "status": "Not Found",
  "errorCode": "404",
  "errorMessage": "Not Found",
  "statusCode": "404"
}

Internal Server Error. Unexpected error occurred while processing the request.

{
  "status": "Internal Server Error",
  "errorCode": "500",
  "errorMessage": "Unexpected server error.",
  "statusCode": "500"
}

Responses

Status	Meaning	Description	Schema
200	OK	Tabulation retrieved successfully.	Combination
400	Bad Request	Bad Request. The request parameters are invalid.	Problem
401	Unauthorized	Unauthorized. Missing or invalid API key.	Problem
403	Forbidden	Forbidden. The API key does not grant access to workspaces.	Problem
404	Not Found	Not Found. No workspaces found.	Problem
500	Internal Server Error	Internal Server Error. Unexpected error occurred while processing the request.	Problem

Schemas

Axis

{
  "id": 3,
  "label": "Eje:3",
  "items": [
    {
      "id": "VARIABLE",
      "label": "Label variable",
      "items": [
        {
          "id": "VARIABLE1",
          "label": "Label variable 1"
        },
        {
          "id": "VARIABLE2",
          "label": "Label variable 2"
        }
      ]
    },
    {
      "id": "VARIABLE2",
      "label": "Label variable 2"
    }
  ]
}

Represents a axis.

Properties

Name	Type	Required	Restrictions	Description
id	integer	false	none	Identifier of the axis
label	string	false	none	Label of the axis
items	[Variable]	false	none	List of items in this axis

AxisItem

{
  "axis": "STATISTICS",
  "item": "STATISTICS"
}

Represents a item in axis filter.

Properties

Name	Type	Required	Restrictions	Description
axis	string	false	none	Human-readable label
item	Item	false	none	item seleceted in the axis

Combination

{
  "combinations": 0,
  "itemCombinations": [
    {
      "items": [
        {
          "axis": "STATISTICS",
          "item": {
            "id": "wTotal",
            "label": "Individuos Pond."
          }
        }
      ],
      "sliceId": "string"
    }
  ]
}

Represents a combination of tabulation element.

Properties

Name	Type	Required	Restrictions	Description
combinations	integer(int32)	false	none	Number combinations filters.
itemCombinations	[ItemCombination]	false	none	Links to all plans of a tabulation element.

ConfigRequest

{
  "key": "string",
  "value": "string"
}

Properties

Name	Type	Required	Restrictions	Description
key	string	true	none	none
value	string	true	none	none

Database

{
  "id": "SURVEY MARKET AND MEDIA 2030",
  "description": "General overview of market and media of the world",
  "creationDate": "2025-03-01T16:03:27.592+00:00",
  "updatedDate": "2025-03-01T16:03:27.592+00:00",
  "params": {
    "param1": "value1",
    "param2": "value2"
  }
}

Represents a database entity containing metadata and additional parameters.

Properties

Name	Type	Required	Restrictions	Description
id	string	false	none	Unique identifier of the database.
description	string	false	none	Human-readable description of the database.
creationDate	string(date-time)	false	none	ISO-8601 formatted creation date and time of the database including timezone.
updatedDate	string(date-time)	false	none	ISO-8601 formatted creation date and time of the database including timezone.
params	object	false	none	Additional key-value parameters associated with the database.
» additionalProperties	any	false	none	none

Dimension

{
  "id": "ROWS",
  "axis": [
    {
      "id": "1",
      "label": "STATISTICS",
      "items": [
        {
          "id": "VARIABLE",
          "label": "Label variable",
          "items": [
            {
              "id": "VARIABLE1",
              "label": "Label variable 1"
            },
            {
              "id": "VARIABLE2",
              "label": "Label variable 2"
            }
          ]
        },
        {
          "id": "VARIABLE2",
          "label": "Label variable 2"
        }
      ]
    },
    {
      "id": "2",
      "label": "EJE1",
      "items": [
        {
          "id": "VARIABLE2",
          "label": "Label variable 2"
        }
      ]
    }
  ]
}

Dimension (ROWS, COLUMNS, PLANES)

Properties

Name	Type	Required	Restrictions	Description
id	string	false	none	Identifier of the dimension
axis	[Axis]	false	none	List of axis in this dimension

Element

{
  "id": "A1B2C3D4E5F607182930ABCD12345678",
  "name": "Sample element",
  "creationDate": "2025-03-01T16:03:27.592+00:00",
  "updateDate": "2025-03-01T16:03:27.592+00:00"
}

Represents an element within a workspace with metadata.

Properties

Name	Type	Required	Restrictions	Description
id	string	false	none	Unique identifier of the element.
name	string	false	none	Human-readable name of the element.
creationDate	string(date-time)	false	none	ISO-8601 formatted creation date and time of the element including timezone.
updateDate	string(date-time)	false	none	ISO-8601 formatted last update date and time of the element including timezone.

Item

{
  "id": "D1",
  "label": "HOMBRE"
}

Represents a Item.

Properties

Name	Type	Required	Restrictions	Description
id	string	false	none	Identifier of the Item
label	string	false	none	Label of the axis

ItemCombination

{
  "items": [
    {
      "axis": "STATISTICS",
      "item": {
        "id": "wTotal",
        "label": "Individuos Pond."
      }
    }
  ],
  "sliceId": "string"
}

Represents a combination of plan items.

Properties

Name	Type	Required	Restrictions	Description
items	[AxisItem]	false	none	Identifier of the Items filtered in plans
sliceId	string	false	none	Unique sliceId select filter plan.

Matrix

{
  "items": [
    {
      "axis": "STATISTICS",
      "item": {
        "id": "wTotal",
        "label": "Individuos Pond."
      }
    }
  ],
  "rowCount": 3,
  "columnCount": 9,
  "table": [
    [
      42131.12000000027,
      20457.67321636141,
      21673.44678363881
    ]
  ]
}

Represents a Matrix.

Properties

Name	Type	Required	Restrictions	Description
items	[AxisItem]	false	none	Identifier of the Items filtered in plans
rowCount	number	false	none	Number of rows
columnCount	number	false	none	Number of columns
table	[array]	false	none	Matrix of values representing the table data.

Problem

{
  "status": "string",
  "errorMessage": "string",
  "errorCode": "string",
  "statusCode": 0
}

This represents a problem response

Properties

Name	Type	Required	Restrictions	Description
status	string	false	none	none
errorMessage	string	false	none	none
errorCode	string	false	none	none
statusCode	integer(int32)	false	none	none

Survey

{
  "code": "SURVEY MARKET AND MEDIA 2030",
  "description": "General overview of market and media of the world",
  "creationDate": "2025-03-01T16:03:27.592+00:00",
  "updatedDate": "2025-03-01T16:03:27.592+00:00"
}

Represents a survey with code, description and timestamps.

Properties

Name	Type	Required	Restrictions	Description
code	string	false	none	Unique code of the survey.
description	string	false	none	Human-readable description of the survey.
creationDate	string(date-time)	false	none	ISO-8601 formatted creation date and time of the survey including timezone.
updatedDate	string(date-time)	false	none	ISO-8601 formatted last update date and time of the survey including timezone.

Table

{
  "dimensions": [
    {
      "id": "ROWS",
      "axis": [
        {
          "id": "1",
          "label": "STATISTICS",
          "items": [
            {
              "id": "VARIABLE",
              "label": "Label variable",
              "items": [
                {
                  "id": "VARIABLE1",
                  "label": "Label variable 1"
                },
                {
                  "id": "VARIABLE2",
                  "label": "Label variable 2"
                }
              ]
            },
            {
              "id": "VARIABLE2",
              "label": "Label variable 2"
            }
          ]
        },
        {
          "id": "2",
          "label": "EJE1",
          "items": [
            {
              "id": "VARIABLE2",
              "label": "Label variable 2"
            }
          ]
        }
      ]
    },
    {
      "id": "COLUMNS",
      "axis": [
        {
          "id": "2",
          "label": "EJE1",
          "items": [
            {
              "id": "VARIABLE2",
              "label": "Label variable 2"
            }
          ]
        }
      ]
    }
  ],
  "matrix": "{\n    \"items\":[\n            {\n                \"axis\":\"STATISTICS\",\n                \"item\":{\n                    \"id\":\"wTotal\",\n                    \"label\":\"Individuos Pond.\"\n                }\n            }\n        ],\n    \"rowCount\":\"3\",\n    \"columnCount\":\"9\",\n    \"table\":[\n        [\n            42131.12000000027\n            20457.67321636141\n            21673.44678363881\n        ]\n    ]\n}",
  "combinations": 0,
  "indexCombination": 0,
  "selfTableLink": "string",
  "nextTableLink": "string",
  "previousTableLink": "string"
}

Represents a table.

Properties

Name	Type	Required	Restrictions	Description
dimensions	[Dimension]	false	none	List of dimensions (e.g., ROWS, COLUMNS, PLANES)
matrix	Matrix	false	none	Matrix of formatted cells representing the table data.
combinations	integer(int32)	false	none	Number combinations filters.
indexCombination	integer(int32)	false	none	Index combination actual.
selfTableLink	string	false	none	Link to current tabulation element.
nextTableLink	string	false	none	Link to next tabulation element.
previousTableLink	string	false	none	Link to previos tabulation element.

Variable

{
  "id": "D1",
  "label": "HOMBRE",
  "items": [
    {
      "id": "VARIABLE1",
      "label": "Label variable 1"
    },
    {
      "id": "VARIABLE2",
      "label": "Label variable 2"
    }
  ]
}

Represents a Variable.

Properties

Name	Type	Required	Restrictions	Description
id	string	false	none	Identifier of the Item
label	string	false	none	Label of the axis
items	[Variable]	false	none	List of categories in this item

Variable user

{
  "id": "A1B2C3D4E5F607182930ABCD12345678",
  "label": "Sample element",
  "creationDate": "2025-03-01T16:03:27.592+00:00",
  "updatedDate": "2025-03-01T16:03:27.592+00:00"
}

Represents a variable with metadata and additional parameters.

Properties

Name	Type	Required	Restrictions	Description
id	string	false	none	Unique identifier
label	string	false	none	Human-readable label
creationDate	string(date-time)	false	none	ISO-8601 formatted creation date and time including timezone.
updatedDate	string(date-time)	false	none	ISO-8601 formatted last update date and time including timezone.

Workspace

{
  "id": "A1B2C3D4E5F607182930ABCD12345678",
  "name": "Sample element",
  "surveyCode": "SURVEY MARKET AND MEDIA 2030",
  "surveyDescription": "General overview of market and media of the world",
  "creationDate": "2025-03-01T16:03:27.592+00:00"
}

Represents a workspace with metadata, survey information, and creation timestamp.

Properties

Name	Type	Required	Restrictions	Description
id	string	false	none	Unique identifier of the workspace.
name	string	false	none	Human-readable name of the workspace.
surveyCode	string	false	none	Unique code identifying the workspace survey.
surveyDescription	string	false	none	Human-readable description of the workspace survey.
creationDate	string(date-time)	false	none	ISO-8601 formatted creation date and time of the workspace including timezone.

WorkspaceDetail

{
  "id": "A1B2C3D4E5F607182930ABCD12345678",
  "name": "Sample element",
  "surveyCode": "SURVEY MARKET AND MEDIA 2030",
  "surveyDescription": "General overview of market and media of the world",
  "creationDate": "2025-03-01T16:03:27.592+00:00",
  "tabulations": [
    {
      "id": "31E083AA6B0370B2E063CD6710ACB224",
      "name": "Sales by Region",
      "creationDate": "2023-03-01T00:00:00Z",
      "updateDate": "2023-03-01T00:00:00Z"
    }
  ],
  "targets": [
    {
      "id": "31E083AA6B0370B2E063CD6710ACB224",
      "name": "Target Segment A",
      "creationDate": "2023-03-01T00:00:00Z",
      "updateDate": "2023-03-01T00:00:00Z"
    }
  ],
  "userVars": [
    {
      "id": "31E083AA6B0370B2E063CD6710ACB224",
      "name": "AgeGroup",
      "creationDate": "2023-03-01T00:00:00Z",
      "updateDate": "2023-03-01T00:00:00Z"
    }
  ],
  "surveys": [
    {
      "code": "00000",
      "description": "Example data survey",
      "creationDate": "2023-03-01T00:00:00Z",
      "updateDate": "2023-03-01T00:00:00Z"
    }
  ]
}

Detailed representation of a workspace with related elements.

Properties

Name	Type	Required	Restrictions	Description
id	string	false	none	Unique identifier of the workspace.
name	string	false	none	Human-readable name of the workspace.
surveyCode	string	false	none	Unique code identifying the workspace survey.
surveyDescription	string	false	none	Human-readable description of the workspace survey.
creationDate	string(date-time)	false	none	ISO-8601 formatted creation date and time of the workspace including timezone.
tabulations	[Element]	false	none	List of tabulations associated with the workspace.
targets	[Element]	false	none	List of targets associated with the workspace.
userVars	[Element]	false	none	List of user-defined variables associated with the workspace.
surveys	[Survey]	false	none	List of surveys associated with the workspace.

tom-external-api API v3.10.0-SNAPSHOT

Authentication

1. Surveys

Retrieve surveys

Responses

2. Workspaces

Retrieve workspace by ID

Parameters

Responses

Retrieve workspaces

Responses

3. Variables

Retrieve variables by survey code

Parameters

Responses

4. Tabulation

Retrieve detailed information for a specific tabulation.

Parameters

Responses

Retrieve Plane Combinations for a Tabulation

Parameters

Responses

Schemas

Axis

Properties

AxisItem

Properties

Category

Properties

Combination

Properties

ConfigRequest

Properties

Database

Properties

Dimension

Properties

Element

Properties

Item

Properties

ItemCombination

Properties

Matrix

Properties

Problem

Properties

Survey

Properties

Table

Properties

Variable

Properties

Variable user

Properties

Workspace

Properties

WorkspaceDetail

Properties