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, fromGET /api/v2/users/surveys.- Carrier ids: from
GET /api/v2/survey/{surveyCode}/carriers(items withtype: CARRIER). Insertions are read only from carriers (type: CARRIERor notype); any othertype,FOLDERincluded, is treated as a folder and carries no insertions. The comparison is case-sensitive and nothing is rejected: an unknowntypeis 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 theirinsertionsper 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, so the cost of a carrier in a plan is its price times its insertions in that 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).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 inPOST /api/v2/survey/{surveyCode}/ranking. Withouttargetthe plans are evaluated on the whole population.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, with the same rules as inPOST /api/v2/survey/{surveyCode}/ranking. Without it, the plans are evaluated over the whole population.hierarchy(optional, defaultfalse): whentrue, the carriers' folders are added as grouping rows.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
dimensions[id=ROWS]: aMEDIAaxis whosemediaItemsarray 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 has0insertions in that plan. Each row reports its insertions ininsertions, 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]: aSTATISTICSaxis (itsidisSTATISTICS) whosestatisticsarray lists the columns in order.matrix.table[r][c]: the value ofmediaItems[r]forstatistics[c]. Values are raw numbers; a cell that cannot be calculated is returned as the string"NaN", not asnull.
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.
| 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 evaluations. |
| 400 | AE_ERR_403 | A requested statistic is not available for this survey. |
| 400 | EV_ERR_104 | No carrier has a positive number of insertions. |
| 400 | EV_ERR_103 | A carrier has a negative number of insertions. |
| 400 | SP_ERR_101 | A carrier id does not exist in the survey. |
| 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. |
Errors raised by the calculation engine keep their own errorCode, and their errorMessage can be translated: rely on errorCode.
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 422
- 500
The evaluation calculated: a row for each plan and for each carrier within it, 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 evaluations. AE_ERR_403: a requested statistic is not available for this survey. EV_ERR_104: no carrier has a positive number of insertions. EV_ERR_103: a carrier has a negative number of insertions. SP_ERR_101: a carrier id does not exist in the survey. 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.