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:
-
ROWS – Defines all row carriers. Example items: Axis 1: ABC, ARA, ATLANTICODIARIO.
-
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:
-
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.
Example Mapping
This demonstrates how a cell value is mapped to the full 2D coordinates, using the example data:
| Cell Index | Value | Corresponding 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.filterTglonly → inline target expression; current behavior; no change.target.idonly → 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
idandfilterTglpresent → 400 TargetAmbiguous.
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 500
Ranking Carriers 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.