Calculate a carrier ranking
POST/api/v2/survey/:surveyCode/ranking
Calculates a ranking: the audience statistics you choose for each carrier, side by side, to compare and shortlist carriers before building a media plan.
The ranking is calculated on demand and is not stored. To measure complete media plans, use POST /api/v2/survey/{surveyCode}/evaluation.
Before you call it
surveyCode: a survey available to the user of the API key, fromGET /api/v2/users/surveys.- Carrier ids: from
GET /api/v2/survey/{surveyCode}/carriers(theidof items withtype: CARRIER). - Statistic ids: from
GET /api/v2/statistics?tableType=RANKING. Only statistics that apply to rankings are accepted. - Target and population base (optional): the id of a saved target, from
GET /api/v2/workspace/{workspaceId}/survey/{surveyCode}/targets(it may live in any workspace you can see), or an inline TGL expression (see the TGL guide). - The user needs the Study module.
Request
carriers(required): the carriers to rank. Send each one withtype: CARRIERor withouttype. Any othertype,FOLDERincluded, is treated as a folder of carriers, and itsinsertionsare ignored; joints of carriers (CARRIER_JOINT) are not supported by this operation. The comparison is case-sensitive and nothing is rejected: an unknowntypeis read as a folder.statistics: the statistics to calculate. The columns of the ranking are built from this list, so send at least one: without it, or with an empty list, the ranking returns400(T_ERR_104).target(optional): audience filter. Withouttargetthe ranking covers the whole population. Other target fields are ignored.target.idonly: the saved target with that id is used. It is looked up across all the workspaces visible to the user:404(AE_ERR_406) if it does not exist in any of them,403(AE_ERR_407) if it exists but is not visible to the user.target.filterTglonly: the target is the inline TGL expression.- Both:
filterTglis used andidis ignored. - Neither (
"target": {}):400(AE_ERR_405).
targetBase(optional): the population base, which fixes the reference universe of the percentages. It takes a saved targetidor an inline TGL expression infilterTgl, with the same rule astarget: with both,filterTglwins; with neither,400(AE_ERR_405). A baseidis not looked up beforehand: if it cannot be resolved, the calculation engine returns its error. Without it, the percentages are calculated over the whole population.hierarchy(optional, defaultfalse): whentrue, the carriers' folders are kept as grouping rows above their carriers.insertions(optional, per carrier): each position defines a plan, and the ranking adds one column per plan (PLAN_1,PLAN_2, ...) with the insertions of each carrier. These columns appear only in the response: do not send them instatistics(the ranking answers400AE_ERR_402). For the figures of each plan as a whole, usePOST /api/v2/survey/{surveyCode}/evaluation: each plan has its own row there (type: MEDIA_PLAN).price(optional, per carrier): the net price of one insertion of the carrier, in the currency of the survey. It replaces the price configured for that carrier, as thepriceof an optimization candidate does, and every cost statistic is calculated with it: the list price ones (PRICE,CPM_CONT,CGRP...) and the discounted ones (DISCOUNT_PRICE,DISCOUNT_CPM_CONT...). One price per carrier: it applies to every plan.0is a cost of zero. Without it, the configured price is used. A negative price, or a price on a folder, returns400(AE_ERR_400).titleis ignored by this operation. Unknown fields are ignored.
Deprecated names
Earlier versions used other names for carriers. The type values SUPPORT (for CARRIER) and FAMILY (for FOLDER) are still accepted in requests and are never returned. Use the current names.
Response
A table with two dimensions and one matrix:
dimensions[id=ROWS]: aCARRIERSaxis whosecarriersarray lists the rows in order. Read thetypeof each row: withhierarchy, folder rows (type: FOLDER) appear above their carriers. Theidof the axis (for exampleAXIS_SUPPORTS) is an opaque identifier: read the kind of axis fromaxisType.dimensions[id=COLUMNS]: aSTATISTICSaxis whosestatisticsarray lists the columns in order, thePLAN_ncolumns of the plans included.matrix.table[r][c]: the value of rowcarriers[r]for columnstatistics[c].matrix.rowCountandmatrix.columnCountgive the size. Values are raw numbers; a cell that cannot be calculated is returned as the string"NaN", not asnull.
Always map cells through these arrays, never through the order of your request. Labels follow the language of the user.
Unlike POST /api/v2/table/{surveyCode}, this operation returns a single matrix object, not matrixList, and it has no dataType, locale or decimals options. The calculation is synchronous.
Errors
errorMessage is meant for people and may be in the user's language. Base your error handling on errorCode.
| Status | errorCode | When |
|---|---|---|
| 400 | AE_ERR_405 | target or targetBase has neither a non-blank id nor a non-blank filterTgl. |
| 400 | AE_ERR_400 | carriers is missing, null or empty (an empty or null body included), or a value has the wrong JSON type. |
| 400 | AE_ERR_400 | A price is negative, or is sent on a folder; the message names the carrier. |
| 400 | AE_ERR_412 | An item of carriers or statistics is null or has no id; the message gives its position. |
| 400 | AE_ERR_402 | A statistic does not apply to rankings. |
| 400 | AE_ERR_403 | A requested statistic is not available for this survey. |
| 400 | SP_ERR_101 | A carrier id does not exist in the survey: the whole request is rejected, the id is not skipped. |
| 400 | T_ERR_104 | statistics is missing or empty. |
| 400 | TG_ERR_113 | targetBase.id does not identify a saved target. |
| 400 | TGL_ERR_101 | A filterTgl of target or targetBase uses a variable or category that the survey does not have. |
| 400 | ST_ERR_122 | The survey cannot be used for media planning, for example a consumption-diary (Reach) survey. |
| 400 | E400 | The body is not valid JSON. |
| 400 | SO_ERR_201, SO_ERR_202 | The survey is disabled, being loaded, or deleted. |
| 401 | E401 | The X-API-Key header is missing or empty. |
| 401 | SO_ERR_203 | The survey is not in your profile or does not exist. |
| 403 | AE_ERR_408 | The user does not have the Study module. |
| 403 | AE_ERR_407 | target.id exists but is not visible to the user. |
| 404 | AE_ERR_406 | target.id does not exist in any workspace visible to the user. |
| 422 | TGL_INVALID | A filterTgl of target or targetBase cannot be used: it does not parse, or it uses a variable without a category or a condition. |
| 500 | GEN_ERR_500 | Unexpected error, including a calculation that exceeds the server time limit (about two minutes): retry with fewer carriers or statistics. |
Errors raised by the calculation engine keep the engine's own errorCode, and their errorMessage can be translated: rely on errorCode.
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 422
- 500
The ranking calculated: one row per carrier and one column per statistic.
The request cannot be processed. AE_ERR_400: carriers is missing or empty, or a price is negative or sent on a folder. AE_ERR_412: an item of carriers or statistics is null or has no id. AE_ERR_405: target or targetBase has neither id nor filterTgl. AE_ERR_402: a statistic does not apply to rankings. AE_ERR_403: a requested statistic is not available for this survey. SP_ERR_101: a carrier id does not exist in the survey; the whole request is rejected. T_ERR_104: statistics is missing or empty. TG_ERR_113: targetBase.id does not identify a saved target. TGL_ERR_101: a filterTgl uses a variable or category that the survey does not have. ST_ERR_122: the survey cannot be used for media planning, for example a consumption-diary (Reach) survey. SO_ERR_201, SO_ERR_202: the survey is disabled, being loaded or deleted. E400: the body is not valid JSON.
The X-API-Key header is missing or empty (E401), or the survey is not in the user's profile or does not exist (SO_ERR_203).
The application module this operation needs is not enabled for the user (AE_ERR_408), or the target id exists but is not visible to the user (AE_ERR_407).
target.id does not exist in any workspace visible to the user (AE_ERR_406).
A TGL expression of the request cannot be used (TGL_INVALID): it does not parse, or it uses a variable without a category or condition. An unknown variable or category returns 400 TGL_ERR_101 instead.
Unexpected error, including a calculation that exceeds the server time limit (about two minutes): retry with fewer carriers or statistics.