Skip to main content

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?

OperationQuestion it answersResult
POST /api/v2/survey/{surveyCode}/rankingHow do these carriers compare, side by side?One row per carrier, one column per statistic.
POST /api/v2/survey/{surveyCode}/evaluationWhat 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-curveHow 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, from GET /api/v2/users/surveys. A survey that does not support media planning, such as a Reach survey (availableReach: true), returns 400 ST_ERR_122.
  • Carrier ids: from GET /api/v2/survey/{surveyCode}/carriers, the id of the items with type: CARRIER.
  • Statistic ids: from GET /api/v2/statistics?tableType=RANKING (or EVALUATION). 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 id from GET /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 with type: CARRIER or without type. Any other type, FOLDER included, is treated as a folder of carriers and its insertions are 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; use 0 when a carrier is not in a plan. The number of plans is the length of the longest array. A negative number is rejected with 400 EV_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 returns 400 T_ERR_104.
  • target (optional): an audience filter, with the same rules in every operation of this family: id or filterTgl. With both, filterTgl is used; with neither, 400 AE_ERR_405. A saved target id is 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. Without target, the calculation covers the whole population.
  • targetBase (optional): the population base, the reference universe of the percentages, with the same rules as target. A base id is not looked up beforehand: if it cannot be resolved, the calculation engine returns its error (400 TG_ERR_113 for an id that does not identify a saved target). A saved evaluation keeps its base. Without it, the percentages are calculated over the whole population.
  • hierarchy (optional, default false): when true, the folders of the carriers are kept as grouping rows.
  • title is 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]: 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 opaque: read the kind of axis from axisType.
  • dimensions[id=COLUMNS]: a STATISTICS axis whose statistics array lists the columns in order.
  • matrix.table[r][c]: the value of row carriers[r] for column statistics[c]. Values are raw numbers; a cell that cannot be calculated is the string "NaN", not null.

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 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. The plan row holds the figures of the plan as a whole: there is no separate total row.
  • dimensions[id=COLUMNS] is a STATISTICS axis, and its id is STATISTICS.
  • matrix.table[r][c] is the value of mediaItems[r] for statistics[c]. A cell that cannot be calculated is the string "NaN", not 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. 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 is 400 VAL_ERR_001; the default is EVALUATION). With target.id, the element stores a reference to the saved target; with target.filterTgl, it stores the expression.
  • workspaceId must be a workspace you own. A workspace shared with you cannot be written to.
  • The response describes the created element (id, name, title, description, enabled and 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 is 400.
  • includeTotalPlan: also returns the total plan, every plan taken together, in total. Its insertions is 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 as 1, 2, 3, 4-15 and >15. A value that is not positive, out of order or repeated is rejected with 400 AE_ERR_400.
  • Weighting, either one but not both (sending both is 400): weightings is 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%); memorizationCoefficient is a percentage in integer form (12 means 12%) that is the chance of remembering a single contact, compounding over successive ones. Send a memorizationCoefficient from 0 to 100: any other value is rejected with 400 AE_ERR_400. Only integers are accepted: a decimal is rejected, never rounded.

Reading the response:

  • intervals echoes the ranges used.
  • plans has one entry per plan, in the order of insertions, with index (starting at 1), label, the insertions of the plan, its statistics (cover, cover percentage, contacts, GRP, OTS and maximum cover) and its curves. total has 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) and PERCENT_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) and accumulated (the share reached at least that number of times). accumulated is the response curve.
  • statisticList names 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 errorCodeCause
400 AE_ERR_405target or targetBase has neither a non-blank id nor a non-blank filterTgl.
400 AE_ERR_402A statistic does not apply to this operation (ranking, evaluation).
400 AE_ERR_403A requested statistic is not available for this survey (ranking, evaluation).
400 AE_ERR_400Response 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_412An 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_104Ranking: statistics is missing or empty.
400 SP_ERR_101A carrier id does not exist in the survey. The whole request is rejected; the id is not skipped.
400 EV_ERR_103A negative number of insertions.
400 EV_ERR_104No carrier has a positive number of insertions (evaluation and saving).
400 ST_ERR_122The survey does not support media planning, for example a Reach survey.
400 TG_ERR_113targetBase has an id that does not identify a saved target.
400 TGL_ERR_101An inline filterTgl uses a variable or category that does not exist in the survey.
400 VAL_ERR_001Saving: title is longer than 100 characters.
400 WS_ERR_101, WS_ERR_403Saving: the workspace does not exist, or you do not own it.
400 SO_ERR_201, SO_ERR_202The survey is disabled, being loaded or deleted.
401 SO_ERR_203The survey is not in your profile or does not exist.
403 AE_ERR_408The user does not have the Study module.
403 AE_ERR_407target.id exists but the user cannot see it.
404 AE_ERR_406target.id does not exist in any workspace visible to the user.
422 TGL_INVALIDAn inline filterTgl cannot be parsed.
500 GEN_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 their own errorCode. See Errors and troubleshooting.