Media planning: ranking, evaluation and response curve
Three operations share one request model, carriers, and one question: how well do these media reach this audience?
| Operation | Question it answers | Result |
|---|---|---|
POST /api/v2/survey/{surveyCode}/ranking | How do these carriers compare, side by side? | One row per carrier, one column per statistic. |
POST /api/v2/survey/{surveyCode}/evaluation | What do one or more media plans deliver, plan by plan and carrier by carrier? | One row per plan and per carrier of the plan, one column per statistic. |
POST /api/v2/survey/{surveyCode}/response-curve | How is the audience of each plan spread by number of contacts? | The share reached once, twice, three times and so on. |
All of them are calculated on demand and nothing is stored, and they need the Study module. A fourth operation, POST /api/v2/survey/{surveyCode}/evaluation/save/{workspaceId}, saves an evaluation in a workspace.
1. Before you call
surveyCode: a survey available to the user, fromGET /api/v2/users/surveys. A survey that does not support media planning, such as a Reach survey (availableReach: true), returns400ST_ERR_122.- Carrier ids: from
GET /api/v2/survey/{surveyCode}/carriers, theidof the items withtype: CARRIER. - Statistic ids: from
GET /api/v2/statistics?tableType=RANKING(orEVALUATION). Only statistics that apply to the operation are accepted. The ids of each table type are fixed: an id that exists keeps its name and its meaning, and new ones can be added, so do not fail on an id you do not know. - A target (optional): a saved target
idfromGET /api/v2/workspace/{workspaceId}/survey/{surveyCode}/targets, or an inline TGL expression. See the TGL guide.
2. The request model
{
"carriers": [
{ "id": "TVCH1005D1F1", "insertions": [2, 2] },
{ "id": "TVCH1005D1F2", "insertions": [2, 1] }
],
"statistics": [{ "id": "CONTACT" }, { "id": "GRP" }, { "id": "COVER" }, { "id": "COVER_PERCENT" }],
"target": { "filterTgl": "SEX.D2" }
}
carriers(required): the carriers to calculate. Send each one withtype: CARRIERor withouttype. Any othertype,FOLDERincluded, is treated as a folder of carriers and itsinsertionsare ignored; nothing is rejected. Joints of carriers (CARRIER_JOINT) are not supported here.insertions: each position of the 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.[2, 1]puts the carrier twice in plan 1 and once in plan 2; use0when a carrier is not in a plan. The number of plans is the length of the longest array. A negative number is rejected with400EV_ERR_103.statistics: the statistics to calculate. A ranking builds its columns from this list, so send at least one: without it, or with an empty list, a ranking returns400T_ERR_104.target(optional): an audience filter, with the same rules in every operation of this family:idorfilterTgl. With both,filterTglis used; with neither,400AE_ERR_405. A saved targetidis looked up in 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 the user cannot see it. Withouttarget, the calculation covers the whole population.targetBase(optional): the population base, the reference universe of the percentages, with the same rules astarget. A baseidis not looked up beforehand: if it cannot be resolved, the calculation engine returns its error (400TG_ERR_113for anidthat does not identify a saved target). A saved evaluation keeps its base. Without it, the percentages are calculated over the whole population.hierarchy(optional, defaultfalse): whentrue, the folders of the carriers are kept as grouping rows.titleis ignored by ranking and evaluation. Unknown fields are ignored.
3. Ranking
A ranking calculates the statistics you choose for each carrier, so that you can compare carriers and shortlist them before you build a plan. If you add insertions to the carriers, the ranking adds one column per plan (PLAN_1, PLAN_2, ...) with the insertions of each carrier.
{
"carriers": [{ "id": "TVCH1005D1F1" }, { "id": "TVCH1005D1F2" }, { "id": "TVCH1005D2F1" }],
"statistics": [{ "id": "CONTACT" }, { "id": "GRP" }, { "id": "COVER" }, { "id": "COVER_PERCENT" }]
}
The response is 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 opaque: read the kind of axis fromaxisType.dimensions[id=COLUMNS]: aSTATISTICSaxis whosestatisticsarray lists the columns in order.matrix.table[r][c]: the value of rowcarriers[r]for columnstatistics[c]. Values are raw numbers; a cell that cannot be calculated is the string"NaN", notnull.
Always map cells through these arrays, never through the order of your request. Unlike POST /api/v2/table/{surveyCode}, a ranking returns a single matrix object, not matrixList, and it has no dataType, locale or decimals options.
4. Evaluation
An evaluation measures one or more complete plans: each plan as a whole and every carrier within it.
{
"carriers": [
{ "id": "TVCH1005D1F1", "insertions": [2, 2] },
{ "id": "TVCH1005D1F2", "insertions": [2, 1] },
{ "id": "TVCH1005D2F1", "insertions": [1, 2] }
],
"statistics": [{ "id": "CONTACT" }, { "id": "GRP" }, { "id": "COVER" }, { "id": "COVER_PERCENT" }],
"target": { "id": "4B81EAA3CCF416C9E063CD6710AC823E" }
}
At least one carrier must have a positive number of insertions (EV_ERR_104). If you omit statistics, the statistics configured for evaluations in the user's TOM settings are returned.
The response has a MEDIA axis in the rows and a STATISTICS axis in the columns:
dimensions[id=ROWS]is 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. The plan row holds the figures of the plan as a whole: there is no separate total row.dimensions[id=COLUMNS]is aSTATISTICSaxis, and itsidisSTATISTICS.matrix.table[r][c]is the value ofmediaItems[r]forstatistics[c]. A cell that cannot be calculated is the string"NaN", notnull.
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. An evaluation also returns a single matrix, not matrixList.
5. Save an evaluation
POST /api/v2/survey/{surveyCode}/evaluation/save/{workspaceId} calculates an evaluation exactly like the evaluation operation and saves it as a new study element of the workspace, so that it can be opened later in the TOM web application.
- Send the same body, plus an optional
title(up to 100 characters, a longer one is400VAL_ERR_001; the default isEVALUATION). Withtarget.id, the element stores a reference to the saved target; withtarget.filterTgl, it stores the expression. workspaceIdmust be a workspace you own. A workspace shared with you cannot be written to.- The response describes the created element (
id,name,title,description,enabledand dates), not the figures. Call the evaluation operation when you need the numbers. - Not idempotent: every successful call creates a new element, even with an identical body. After a failure or a timeout, check in the TOM web application before you retry.
- A saved evaluation is a study element. It is not listed by
GET /api/v2/workspace/{workspaceId}and cannot be read back through the API: open it in the TOM web application.
6. Response curve
A response curve shows, of everyone a plan reaches, the share reached exactly once, twice, three times and so on, and the share reached at least that many times. It takes the same carriers and insertions as an evaluation, so you can compare several plans in a single call.
{
"carriers": [
{ "id": "TVCH1005D1F1", "insertions": [3, 2] },
{ "id": "TVCH1005D1F2", "insertions": [2, 1] },
{ "id": "TVCH1005D2F1", "insertions": [1, 1] }
],
"planLabels": ["Week 1", "Week 2"],
"includeTotalPlan": true,
"intervals": [1, 2, 3, 5],
"target": { "filterTgl": "SEX.D1" }
}
Fields specific to the curve:
planLabels: names for the plans, matched by position. They do not affect the calculation. More labels than plans is400.includeTotalPlan: also returns the total plan, every plan taken together, intotal. Itsinsertionsis the sum of every plan.intervals: the contact intervals. They default to 1 to 19, plus an open interval above the last one. Send positive integers in ascending order, each the top of a range:[1, 2, 3, 15]comes back as1,2,3,4-15and>15. A value that is not positive, out of order or repeated is rejected with400AE_ERR_400.- Weighting, either one but not both (sending both is
400):weightingsis a percentage applied to each range on its own, the open one included, and the last value carries over to the remaining ranges ([12, 100]weights the first contact at 12% and everything from the second on at 100%);memorizationCoefficientis a percentage in integer form (12means 12%) that is the chance of remembering a single contact, compounding over successive ones. Send amemorizationCoefficientfrom 0 to 100: any other value is rejected with400AE_ERR_400. Only integers are accepted: a decimal is rejected, never rounded.
Reading the response:
intervalsechoes the ranges used.planshas one entry per plan, in the order ofinsertions, withindex(starting at 1),label, theinsertionsof the plan, itsstatistics(cover, cover percentage, contacts, GRP, OTS and maximum cover) and itscurves.totalhas the same structure for the total plan.- Each plan carries two curves, named in
curves[].statistic:COVER_PERCENT(share of the universe, or of the target population) andPERCENT_COVER(share of the people the plan reaches). They count the same people and differ only in what they are divided by. - Every curve has two arrays aligned with
intervals, in percentage points:distribution(the share reached exactly that number of times) andaccumulated(the share reached at least that number of times).accumulatedis the response curve. statisticListnames and explains both curves in the language of the user.
Weighting also applies to the plan statistics. To compare with the unweighted curve, make a second call without weighting.
7. Errors
Status and errorCode | Cause |
|---|---|
400 AE_ERR_405 | target or targetBase has neither a non-blank id nor a non-blank filterTgl. |
400 AE_ERR_402 | A statistic does not apply to this operation (ranking, evaluation). |
400 AE_ERR_403 | A requested statistic is not available for this survey (ranking, evaluation). |
400 AE_ERR_400 | Response curve: no carriers, a carrier without insertions, memorizationCoefficient with weightings or outside 0 to 100, intervals that are not positive and strictly ascending, more planLabels than plans or more weightings than ranges. |
400 AE_ERR_412 | An item of carriers or statistics is null or has no id, or (response curve) intervals or weightings has a null item. The message gives its position. |
400 T_ERR_104 | Ranking: statistics is missing or empty. |
400 SP_ERR_101 | A carrier id does not exist in the survey. The whole request is rejected; the id is not skipped. |
400 EV_ERR_103 | A negative number of insertions. |
400 EV_ERR_104 | No carrier has a positive number of insertions (evaluation and saving). |
400 ST_ERR_122 | The survey does not support media planning, for example a Reach survey. |
400 TG_ERR_113 | targetBase has an id that does not identify a saved target. |
400 TGL_ERR_101 | An inline filterTgl uses a variable or category that does not exist in the survey. |
400 VAL_ERR_001 | Saving: title is longer than 100 characters. |
400 WS_ERR_101, WS_ERR_403 | Saving: the workspace does not exist, or you do not own it. |
400 SO_ERR_201, SO_ERR_202 | The survey is disabled, being loaded or deleted. |
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 the user cannot see it. |
404 AE_ERR_406 | target.id does not exist in any workspace visible to the user. |
422 TGL_INVALID | An inline filterTgl cannot be parsed. |
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 their own errorCode. See Errors and troubleshooting.