Skip to main content

Retrieve detailed information for ranking carriers (supports target by id).

POST 

/api/v1/survey/:surveyCode/ranking

This method retrieves detailed data for a specific ranking, which represented as a two-dimensional data slice.

A Ranking is structured by two main dimensions: ROWS and COLUMNS. These dimensions contain one axis (containers for carriers or statistical elements).

the ROWS, COLUMNS dimensions.

Response Body Structure

The response contains two main sections: dimensions (the metadata) and matrix (the data slice).

the ROWS, COLUMNS dimensions.

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:

  1. ROWS – Defines all row carriers. Example items: Axis 1: ABC, ARA, ATLANTICODIARIO.

  2. COLUMNS – Defines all column statistics on carriers. Example items: Axis 2: CONTACT, GRP, COVER, COVER_PERCENT.

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[].table: A two-dimensional array of numeric values. Each value is the result of a unique intersection point from the two 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:

  1. ROWS – (First Index [r]): The outer array index (row) corresponds to a specific item from the ROWS dimension.

  2. COLUMNS - (Second Index [c]): The inner array index (column) corresponds to a specific item from the COLUMNS dimension.

Example Mapping

This demonstrates how a cell value is mapped to the full 2D coordinates, using the example data:

Cell IndexValueCorresponding Data Point
table[0][0]42623.77{ROW: ABC, COLUMN: CONTACT}
table[1][2]1358.40{ROW: ABC, COLUMN: GRP}
table[2][8]2892.27{ROW: ABC, COVER: CONTACT}

The optional target field supports two mutually exclusive modes:

  • target.filterTgl only → inline target expression; current behavior; no change.
  • target.id only → target-by-id; the API resolves the target across all workspaces visible to the authenticated user and inlines the TGL before calculation. Returns 404 if the target id is not found in any visible workspace. Returns 403 if the target exists but is not accessible.
  • Both id and filterTgl present → 400 TargetAmbiguous.

Request​

Responses​

Ranking Carriers retrieved successfully