Amplified Intelligence - attentionPLAN® API (1.0.0)

Download OpenAPI specification:Download

API reference for the attentionPLAN® API, including attention data, brand uplift, and Attention-adjuted® reach curve endpoints.

If run into unexpected issues, please reach out to us at plan-support@amplifiedintelligence.com.au with the error message and trace ID (if applicable) for assistance.

Attention data

Get JSON schema

Returns Attention data endpoint metadata JSON Schema.

Responses

Response samples

200
401

Content type

application/json

{"ad_channel_code": "bvod",
"ad_format_code": "bvod.tvc-10-sec",
"countries": "ae",
"age_groups": "18-24",
"genders": "male",
"times_of_day": "pre-morning",
"days_of_week": "monday",
"ad_types": "static",
"min_ad_length_seconds": 100,
"max_ad_length_seconds": 100,
"is_only_mrc_compliant": true,
"average_active_attention_seconds": 0,
"average_passive_attention_seconds": 0,
"average_inactive_attention_seconds": 0,
"average_ad_length_seconds": 0,
"average_ad_time_on_screen_seconds": 0
}

Get attention data

Returns an array of aggregated attention data per each advertising format with the parameters applied.

If the data sample is insufficient for a format, the result won't be returned. Suggestion to generalise input parameters to query from a broader data pool.

Note that invalid parameters and invalid values passed to the parameters in the request's body will be ignored.

Request Body schema: application/json

	Array of objects or null (ChannelRequestDto)
countries	Array of strings or null Enum: "ae" "au" "be" "ca" "de" "fr" "ie" "mx" "nz" "sa" "gb" "us" Filter attention data by country (optional). If no argument is given, the data across all available countries will be returned. Access permission is required to request country-specific data.
age_groups	Array of strings or null Enum: "18-24" "25-34" "35-44" "45-54" "55+" Filter attention data by age group (optional). If no argument is given, the data across all available age groups will be returned.
genders	Array of strings or null Enum: "male" "female" "other" Filter attention data by gender (optional). If no argument is given, the data across all available genders will be returned.
times_of_day	Array of strings or null Enum: "pre-morning" "morning" "afternoon" "evening" Filter attention data by time of day (optional). If no argument is given, the data across all available times of day will be returned.
days_of_week	Array of strings or null Enum: "monday" "tuesday" "wednesday" "thursday" "friday" "saturday" "sunday" Filter attention data by day of week (optional). If no argument is given, the data across all available days of week will be returned.
ad_types	Array of strings or null Enum: "static" "video" Filter attention data by ad type (optional). If no argument is given, the data across all available ad types will be returned.
min_ad_length_seconds	number or null <double> [ 0 .. 100 ] Filter attention data by minimum ad length (optional). Data includes all ad views with ad lengths bigger than or equal to the given minimum ad length. If no argument is given, the data across all available minimum ad lengths will be returned.
max_ad_length_seconds	number or null <double> [ 0 .. 100 ] Filter attention data by maximum ad length (optional). Data includes all ad views with ad lengths smaller than or equal to the given maximum ad length. If no argument is given, the data across all available maximum ad lengths will be returned.
is_only_mrc_compliant	boolean or null Default: false Filter attention data by MRC viewable standard compliance (optional). Only applicable to social channels and general web. Setting this to True means querying only data that meets the MRC Viewability standard (50% in-view for at least 1 second for display ads and 2 seconds for video ads), while setting this to False means including all data. If no argument is given, all data will be included.

Responses

Request samples

Payload

Content type

application/json

{"channels": [{"ad_channel_code": "bvod",
"ad_format_codes": ["bvod.tvc-10-sec"
]
}
],
"countries": ["ae"
],
"age_groups": ["18-24"
],
"genders": ["male"
],
"times_of_day": ["pre-morning"
],
"days_of_week": ["monday"
],
"ad_types": ["static"
],
"min_ad_length_seconds": 100,
"max_ad_length_seconds": 100,
"is_only_mrc_compliant": false
}

Response samples

200
401
403

Content type

application/json

[{"ad_channel": {"name": "string",
"code": "string"
},
"ad_format": {"name": "string",
"code": "string"
},
"average_active_attention_seconds": 0,
"average_passive_attention_seconds": 0,
"average_inactive_attention_seconds": 0,
"average_ad_length_seconds": 0,
"average_ad_time_on_screen_seconds": 0
}
]

Get brand uplift

Brand uplift is the change in the likelihood of a brand being considered at a purchase occassion, as a result of a campaign on an advertising channel. This endpoint returns an average uplift value among all brands advertised on a channel.

Request Body schema: application/json

Array

string

Enum: "spotify" "radio"

Responses

Request samples

Payload

Content type

application/json

["spotify"
]

Response samples

200
401
403

Content type

application/json

[{"ad_channel": {"name": "string",
"code": "string"
},
"brand_uplift": 0
}
]

Attention-adjusted reach curve

Get reach curve

Returns an attentive reach curve where each impression gets a certain amount of attention.

The resultant reach curve responses may experience low degrees of variances for the same output due to probabilistic sampling.

If data is insufficient, a curated and recommended dataset will be used as an alternative to ensure optimal prediction output.

Note that invalid parameters and invalid values passed to the parameters in the request’s body will be ignored.

Request Body schema: application/json

countries	Array of strings or null Enum: "ae" "au" "be" "ca" "de" "fr" "ie" "mx" "nz" "sa" "gb" "us" Generate attentive reach curve based on country-specific data (optional). If no argument is given, the data across all available countries will be taken into calculation. Access permission is required to request country-specific data.
age_groups	Array of strings or null Enum: "18-24" "25-34" "35-44" "45-54" "55+" Generate attentive reach curve based on age group-specific data (optional). If no argument is given, the data across all available age groups will be taken into calculation.
genders	Array of strings or null Enum: "male" "female" "other" Generate attentive reach curve based on gender-specific data (optional). If no argument is given, the data across all available genders will be taken into calculation.
attention_types	Array of strings or null Default: "active" Enum: "active" "passive" The types of attention data that is used to generate attentive reach curve. Including both active and passive means the number of total attention seconds will be taken into calculation. If no argument is given, only active attention will be evaluated.
attention_seconds_threshold	number or null <double> >= 0 Default: 1 The attention second threshold that is applied to each impression to generate the attentive reach curve. If no argument is given, a threshold of 1 second will be taken into calculation.
	Array of objects (ChannelReachCurveRequestDto)

Responses

Request samples

Payload

Content type

application/json

{"countries": ["ae"
],
"age_groups": ["18-24"
],
"genders": ["male"
],
"attention_types": "active",
"attention_seconds_threshold": 1,
"channels": [{"reach_metric": "budget",
"ad_channel_code": "bvod",
"reach_curve_points": [{"x": 0,
"y": 1
}
],
"formats": [{"ad_format_code": "bvod.tvc-10-sec",
"ad_format_mix": 1
}
]
}
]
}

Response samples

200
401
403

Content type

application/json

[{"ad_channel_code": "bvod",
"reach_metric": "trp",
"adjusted_reach_curve_points": [{"x": 0,
"y": 1
}
]
}
]