Skip to main content

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, from GET /api/v2/users/surveys.
  • Carrier ids: from GET /api/v2/survey/{surveyCode}/carriers (the id of items with type: 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 with type: CARRIER or without type. Any other type, FOLDER included, is treated as a folder of carriers, and its insertions are ignored; joints of carriers (CARRIER_JOINT) are not supported by this operation. The comparison is case-sensitive and nothing is rejected: an unknown type is 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 returns 400 (T_ERR_104).
  • target (optional): audience filter. Without target the ranking covers the whole population. Other target fields are ignored.
    • target.id only: 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.filterTgl only: the target is the inline TGL expression.
    • Both: filterTgl is used and id is ignored.
    • Neither ("target": {}): 400 (AE_ERR_405).
  • targetBase (optional): the population base, which fixes the reference universe of the percentages. It takes a saved target id or an inline TGL expression in filterTgl, with the same rule as target: with both, filterTgl wins; with neither, 400 (AE_ERR_405). A base id is 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, default false): when true, 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 in statistics (the ranking answers 400 AE_ERR_402). For the figures of each plan as a whole, use POST /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 the price of 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. 0 is a cost of zero. Without it, the configured price is used. A negative price, or a price on a folder, returns 400 (AE_ERR_400).
  • title is 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]: a CARRIERS axis whose carriers array lists the rows in order. Read the type of each row: with hierarchy, folder rows (type: FOLDER) appear above their carriers. The id of the axis (for example AXIS_SUPPORTS) is an opaque identifier: read the kind of axis from axisType.
  • dimensions[id=COLUMNS]: a STATISTICS axis whose statistics array lists the columns in order, the PLAN_n columns of the plans included.
  • matrix.table[r][c]: the value of row carriers[r] for column statistics[c]. matrix.rowCount and matrix.columnCount give the size. Values are raw numbers; a cell that cannot be calculated is returned as the string "NaN", not as null.

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.

StatuserrorCodeWhen
400AE_ERR_405target or targetBase has neither a non-blank id nor a non-blank filterTgl.
400AE_ERR_400carriers is missing, null or empty (an empty or null body included), or a value has the wrong JSON type.
400AE_ERR_400A price is negative, or is sent on a folder; the message names the carrier.
400AE_ERR_412An item of carriers or statistics is null or has no id; the message gives its position.
400AE_ERR_402A statistic does not apply to rankings.
400AE_ERR_403A requested statistic is not available for this survey.
400SP_ERR_101A carrier id does not exist in the survey: the whole request is rejected, the id is not skipped.
400T_ERR_104statistics is missing or empty.
400TG_ERR_113targetBase.id does not identify a saved target.
400TGL_ERR_101A filterTgl of target or targetBase uses a variable or category that the survey does not have.
400ST_ERR_122The survey cannot be used for media planning, for example a consumption-diary (Reach) survey.
400E400The body is not valid JSON.
400SO_ERR_201, SO_ERR_202The survey is disabled, being loaded, or deleted.
401E401The X-API-Key header is missing or empty.
401SO_ERR_203The survey is not in your profile or does not exist.
403AE_ERR_408The user does not have the Study module.
403AE_ERR_407target.id exists but is not visible to the user.
404AE_ERR_406target.id does not exist in any workspace visible to the user.
422TGL_INVALIDA filterTgl of target or targetBase cannot be used: it does not parse, or it uses a variable without a category or a condition.
500GEN_ERR_500Unexpected 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​

The ranking calculated: one row per carrier and one column per statistic.