Calculate the response curve of a media plan
POST/api/v2/survey/:surveyCode/response-curve
Calculates the response curve of one or more media plans: of everyone a plan reaches, the share reached exactly once, twice, three times and so on.
It also gives the share reached at least that many times (1+, 2+, 3+). It takes the same carriers and insertions as POST /api/v2/survey/{surveyCode}/evaluation, so you can compare several plans in a single call.
Before you call it
- The user behind the API key needs the Study module.
- Take carrier ids from
GET /api/v2/survey/{surveyCode}/carriers, and saved target ids fromGET /api/v2/workspace/{workspaceId}/survey/{surveyCode}/targets.
Plans
Each position of the insertions array of a carrier defines a plan, so insertions: [0, 1, 2] produces three plans. The response carries one entry per plan, in that same order, with index stating which one, starting at 1. The number of plans is the length of the longest insertions array: a carrier with a shorter array has no insertions in the remaining plans, and a plan with no insertions at all comes back with every value at zero. Name the plans with planLabels, matched by position; the names do not affect the calculation.
Only individual carriers carry insertions: send carriers with type omitted or CARRIER. Any other type, FOLDER included, is treated as a folder and its insertions are ignored, although every carrier must still send an insertions array. The comparison is case-sensitive and nothing is rejected: an unknown type is read as a folder.
Set includeTotalPlan to also get the total plan, every plan taken together, in total. Its insertions is the sum of every plan.
Audience
target restricts the calculation to an audience: a saved target id or an inline TGL expression in filterTgl; with both, filterTgl is used, and a target with neither returns AE_ERR_405. Without target, the curve covers the whole universe of the survey.
targetBase is the population base, which fixes the reference universe of the percentages, with the same rule as target. 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 universe of the survey.
Contact intervals
The contact intervals default to 1 to 19, plus an open interval above the last one. Send intervals to ask for others: positive integers in ascending order, each one the top of a range, so [1, 2, 3, 15] comes back as 1, 2, 3, 4-15 and >15. Values that are not positive, out of order or repeated are rejected with 400 (AE_ERR_400). The response always echoes the ranges it used.
Weighting
The curve can be weighted in two ways, which are mutually exclusive: sending both is rejected with 400.
weightings: a percentage applied to each range on its own, the open one included. The last value carries over to the remaining ranges, so[12, 100]weights the first contact at 12% and everything from the second on at 100%.memorizationCoefficient: a percentage in integer form (12means 12%) that is the chance of remembering a single contact, compounding over successive ones. Of the people reached exactlyntimes, the share that remembers is1 - (1 - coefficient/100)^n. Send a value from 0 to 100: any other is rejected with400(AE_ERR_400).
Weighting also applies to the plan statistics: the weighted cover is lower and the OTS higher than without it. To compare with the unweighted curve, make a second call without weighting. Only integers are accepted in intervals, weightings and memorizationCoefficient: a decimal is rejected, never rounded.
Two sizes are rejected with 400: more planLabels than plans, and more weightings than ranges (one more than the intervals, because the open range is weightable too).
Reading the response
Every curve comes as two arrays aligned with intervals, with the same length and order, in percentage points:
distribution: the share reached exactly that number of times.accumulated: the share reached at least that number of times (the 1+, 2+, 3+ reading). This is the response curve.
Each plan carries two curves, named in curves[].statistic and always in this order. They count the same people and differ only in what they are divided by:
COVER_PERCENT: share of the universe, or of thetargetpopulation. Its first accumulated value equalsstatistics.coverPercent.PERCENT_COVER: share of the people the plan reaches. Its first accumulated value is 100 whenever the plan reaches anyone, and 0 for a plan that reaches nobody.
statisticList, at the root of the response, names and explains both curves in the language of the API key's user. statistics adds the totals of each plan: cover, cover percentage, contacts, GRP, OTS and maximum cover.
The body also accepts the evaluation fields title and statistics; they do not change the response. It accepts the price of each carrier too, with the same rules as in the evaluation, so the body of an evaluation with prices can be sent as it is: the price is applied, but the figures of the curve do not change, because the curve returns no cost statistic.
Deprecated names
Earlier versions used other names for carriers. The type values SUPPORT (for CARRIER) and FAMILY (for FOLDER) are still accepted in requests. Use the current names.
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_400 | carriers is missing, null or empty (an empty or null body included), a carrier has no insertions, memorizationCoefficient is sent with weightings or is outside 0 to 100, intervals are not positive and strictly ascending, there are more planLabels than plans, or more weightings than ranges. |
| 400 | AE_ERR_400 | A price is negative, or is sent on a folder; the message names the carrier. |
| 400 | AE_ERR_400 | A decimal or non-numeric value in memorizationCoefficient, weightings or intervals, or any other value of the wrong JSON type. The message names the field. |
| 400 | AE_ERR_412 | An item of carriers or statistics is null or has no id, or intervals or weightings has a null item; the message gives its position. |
| 400 | AE_ERR_405 | target or targetBase has neither a non-blank id nor a non-blank filterTgl. |
| 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. |
| 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_407 | The saved target exists but is not visible to the user. |
| 403 | AE_ERR_408 | The user does not have the Study module. |
| 404 | AE_ERR_406 | The saved 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. |
Errors raised by the calculation engine keep their own status and errorCode.
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 422
- 500
The response curve of every plan, plus the total plan when includeTotalPlan is true.
The body is invalid. AE_ERR_400: carriers is missing or empty, a carrier has no insertions, memorizationCoefficient is sent together with weightings or is outside 0 to 100, intervals are not positive and strictly ascending, there are more planLabels than plans, or more weightings than ranges, or a price is negative or sent on a folder; also a decimal or non-numeric value in memorizationCoefficient, weightings or intervals. AE_ERR_412: a null item in a list, or an item of carriers or statistics without id. AE_ERR_405: target or targetBase has neither id nor filterTgl. 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.
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.