Skip to main content

Calculate a media plan evaluation

POST 

/api/v2/survey/:surveyCode/evaluation

Evaluates one or more media plans and returns their audience statistics: each plan as a whole, and every carrier within each plan.

The evaluation is calculated on demand and is not stored; to keep it, send the same body to POST /api/v2/survey/{surveyCode}/evaluation/save/{workspaceId}. For the frequency distribution of the same plans, use POST /api/v2/survey/{surveyCode}/response-curve.

How plans are defined​

Each carrier has an insertions array, and each position of that array is a plan: insertions[0] is the number of insertions of the carrier in plan 1, insertions[1] in plan 2, and so on. "insertions": [2, 1] puts the carrier twice in plan 1 and once in plan 2; use 0 when a carrier is not in a plan. The number of plans is the length of the longest array, and plans are named Plan 1, Plan 2, ... At least one carrier must have a positive number of insertions.

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 (items with type: CARRIER). Insertions are read only from carriers (type: CARRIER or no type); any other type, FOLDER included, is treated as a folder and carries no insertions. The comparison is case-sensitive and nothing is rejected: an unknown type is read as a folder.
  • Statistic ids: from GET /api/v2/statistics?tableType=EVALUATION.
  • Target and population base (optional): the id of a saved target, from GET /api/v2/workspace/{workspaceId}/survey/{surveyCode}/targets, or an inline TGL expression (see the TGL guide).
  • The user needs the Study module.

Request​

  • carriers (required): carriers with their insertions per 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, so the cost of a carrier in a plan is its price times its insertions in that 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).
  • statistics (optional): the statistics to calculate. If omitted, the statistics configured for evaluations in the user's TOM settings are returned. Even when you send them, planning columns enabled in those settings (for example a start date) may also appear.
  • target (optional): audience filter, with the same rules as in POST /api/v2/survey/{surveyCode}/ranking. Without target the plans are evaluated on the whole population.
    • 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, with the same rules as in POST /api/v2/survey/{surveyCode}/ranking. Without it, the plans are evaluated over the whole population.
  • hierarchy (optional, default false): when true, the carriers' folders are added as grouping rows.
  • 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​

  • dimensions[id=ROWS]: a MEDIA axis whose mediaItems array lists the rows in order, grouped by plan: a plan row (type: MEDIA_PLAN) followed by the rows of its carriers. Every carrier appears under every plan, also when it has 0 insertions in that plan. Each row reports its insertions in insertions, with a single value: the insertions of that plan, or of that carrier in that plan. Insertions are reported there, not as a column. The plan row holds the figures of the plan as a whole: there is no separate total row.
  • dimensions[id=COLUMNS]: a STATISTICS axis (its id is STATISTICS) whose statistics array lists the columns in order.
  • matrix.table[r][c]: the value of mediaItems[r] for statistics[c]. Values are raw numbers; a cell that cannot be calculated is returned as the string "NaN", not as null.

The same carrier id appears once per plan, so identify a carrier row by its position: it belongs to the nearest plan row above it. In the example response below, table[0][1] is the GRP of Plan 1 and table[5][0] is the CONTACT of TVCH1005D1F1 in Plan 2.

This operation returns a single matrix object, not matrixList. Labels follow the language of the user.

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 evaluations.
400AE_ERR_403A requested statistic is not available for this survey.
400EV_ERR_104No carrier has a positive number of insertions.
400EV_ERR_103A carrier has a negative number of insertions.
400SP_ERR_101A carrier id does not exist in the survey.
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.

Errors raised by the calculation engine keep their own errorCode, and their errorMessage can be translated: rely on errorCode.

Request​

Responses​

The evaluation calculated: a row for each plan and for each carrier within it, and one column per statistic.