Digital Platform API - Buyer engagement report
The Buyer Engagement Report gives you insight into the viewable duration of your display and video creatives.
For instructions on retrieving a report, please see Report Service or the example below.
Time frame
The report_interval field in the JSON request can be set to one of the following:
- custom
- yesterday
- last_7_days
- last_14_days
- month_to_yesterday
- last_30_days
Data retention period
Data in this report has a daily time granularity and is retained for five weeks. This report also displays data under the UTC/GMT time zone.
Note
To run a report for a custom time frame, set the start_date and end_date fields in your report request. For more details about these fields, see Report Service.
Dimensions
| Column | Type | Filter? | Example | Description |
|---|---|---|---|---|
advertiser_id |
int | Yes | 3 |
The ID of the advertiser whose creative was served |
advertiser_name |
string | No | "Advertiser" |
The name of the advertiser whose creative was served |
buyer_member_id |
int | Yes | 210 |
The member ID of the buyer |
campaign_id |
int | Yes | 728 |
The ID of the campaign (doesn't apply to all advertisers) |
campaign_name |
string | No | "Test" |
The name of the creative (doesn't apply to all advertisers) |
creative_id |
int | Yes | 554 | The ID of the creative that served. - For impressions older than 14 months, creatives will be aggregated into one row with 0 as the creative ID. Note: For external click or impression trackers, creative_id will be "External Clicks" or "External Imps". |
creative_name |
string | No | "Q1 2010 728x90" |
The name of the creative that served - For impressions older than 14 months, creatives will be aggregated into one row with "All creative data older than 14 months" as the creative name. Note: For external click or impression trackers, creative_name will be "External Clicks" or "External Imps". |
day |
date | Yes | "2012-08-23" |
The day when the impression occurred |
deal_id |
int | Yes | 2345 |
The ID of the deal that the served impression is associated with. - For more information about deals you have negotiated with sellers, see Deal Buyer Access Service. |
deal_name |
string | No | "Private deal for buyer 1085 with floor of $2.50" |
The name of the deal that the served impression is associated with |
device_type |
string | Yes | "Mobile Phones" |
The type of device where the impression occurred: - Desktops & Laptops - Tablets - Mobile Phones - TV - Game Consoles - Set Top Box - Media Players - Other Devices |
domain |
string | No | "bestsiteever.com (1536)" |
The URL and ID of the domain on which the impression occurred |
domain_id |
int | No | 1536 |
The ID of the domain on which the impression occurred |
domain_name |
string | No | "bestsiteever.com" |
The URL of the domain on which the impression occurred |
imp_type |
string | Yes | "External Impression" |
The type of impression that served. For possible values, see imp_type_id. |
imp_type_id |
int | Yes | 3 |
The ID for the type of impression that served (associated types in parentheses): - 1 ("Blank"): No creative served - 2 ("PSA"): A public service announcement served because there were no valid bids and no default creative was available - 3 ("Default Error"): A default creative served due to a timeout issue - 4 ("Default"): A default creative served because there were no valid bids - 5 ("Kept"): Your advertiser's creative served on your publisher's site - 6 ("Resold"): Your publisher's impression was sold to a third-party buyer - 7 ("RTB"): Your advertiser's creative served on third-party inventory - 8 ("PSA Error"): A public service announcement served due to a timeout issue or lack of a default creative - 9 ("External Impression"): An impression from an impression tracker - 10 ("External Click"): A click from a click tracker - 11 ("Insertion"): Your creative served on third-party inventory, where it persists across page-loads and sessions. This impression type is currently only for Facebook News Feed creatives. |
insertion_order_id |
int | No | 648359 |
The ID of the insertion order |
insertion_order_name |
string | No | "InsertionOrderABC" |
The name of the insertion order |
line_item_id |
int | Yes | 947764 |
The ID of the line item that served the impression |
line_item_name |
string | No | "LineItemDEF" |
The name of the line item that served the impression |
media_type |
string | No | "Banner" |
The general display style of the creative that served: - Banner - Interstitial - Video - Text - Expandable - Skin - Facebook |
mediatype_id |
int | Yes | 2 |
The ID of the media type that served |
placement_id |
int | Yes | 546 |
The ID of the placement where the creative was served |
placement_name |
string | No | "300x250 Business" |
The name of the placement where the creative was served |
publisher_id |
int | Yes | 374967 |
The ID of the publisher that owns the inventory |
publisher_name |
string | No | "Publisher XYZ" |
The name of the publisher that owns the inventory |
seller_member_id |
int | Yes | 765 |
The member ID of the seller who sold the impression |
seller_member_name |
string | No | "AdMeld" |
The name of the seller who sold the impression. |
size |
string | Yes | "728x90" |
The size of the creative that was served |
split_id |
int | Yes | 342 |
The ID of the split that purchased the impressions in this data set. Splits are only applicable to augmented line items. For any reports that contain campaigns, the split_id (if included) will be null . |
split_name |
string | No | "Mobile Split A" |
The name of the split that purchased the impressions in this data set. Splits are only applicable to augmented line items. For any reports that contain campaigns, the split_name (if included) will be null . |
supply_type |
string | Yes | "mobile_web" |
The supply (inventory) type on which the impression occurred: - Web - Mobile Web - Mobile App |
Metrics
| Column | Type | Example | Formula | Description |
|---|---|---|---|---|
average_viewable_duration |
seconds | 132297 |
Average Viewable Duration = Total Viewable Duration / Viewable Imps | The average number of seconds for which the creative was in view according to IAB viewability criteria |
clicks |
int | 132297 |
N/A | Your line item's total number of clicks |
ctr |
double | 0.00067472306143 |
N/A | The click-through rate – the ratio of clicks to impressions, expressed as a percentage |
imps |
int | 11080000 |
N/A | Your line item's total number of impressions |
total_viewable_duration |
seconds | 152.4298 |
N/A | The total number of seconds for which the creative was in view according to IAB viewability criteria |
video_completion_rate |
double | 0.0084979838709677 |
Video Completion Rate = Video Completions / Total Impressions | The ratio of video completions to total impressions, expressed as a percentage |
video_completions |
int | 10 |
N/A | The total number of video creatives played for their entire duration |
view_measurable_imps |
int | 11080000 |
N/A | The total number of impressions that were measured for viewability |
view_measurable_rate |
double | 0.00067472306143 |
Viewability Measurement Rate = View Measurable Imps / Imps | The percentage of impressions measured for viewability out of the total number of impressions |
view_rate |
double | 0.00067472306143 |
Viewability Rate = Viewed Imps / View Measurable Imps | The percentage of impressions that were viewable out of the total number of impressions measured for viewability |
viewable_completion_rate |
double | 0.0084979838709677 |
Viewable Completion Rate = Viewable and Completed Video Impressions / Measurable Video Impressions | The ratio of in-view video completions to total impressions, expressed as a percentage |
viewdef_view_rate |
double | 0.00067472306143 |
N/A | The percentage of impressions that were viewable, according to the member-level custom definition configuration, out of the total number of impressions measured for viewability |
viewdef_viewed_imps |
int | 5.678014273984716 |
N/A | The number of measured impressions that were viewable, according to the member-level custom definition configuration (for more details, contact your Xandr account representative) |
viewed_imps |
int | 51.47677411571988 |
N/A | The total number of impressions that were deemed viewable as defined by the Interactive Advertising Bureau (IAB): For at least one second, 50% of a creative's pixels (or 30% for a creative with at least 242,500 pixels) must be viewable to a viewer on their screen. |
Example
Create the JSON-formatted report request
The JSON file should include the report_type "engagement_report_for_buyers", as well as the columns (dimensions and metrics) and report_interval that you want to retrieve. You can also filter for specific dimensions, define granularity (year, month, day), and specify the format in which the data should be returned (csv, excel, or html). For a full explanation of fields that can be included in the JSON file, see Report Service.
$ cat engagement_report_for_buyers
{
"report":
{
"report_type":"engagement_report_for_buyers",
"columns":[
"line_item_id",
"line_item_name",
"creative_name",
"viewable_completion_rate",
"average_viewable_duration",
"ctr",
"clicks",
"imps"
],
"report_interval":"last_7_days",
"format":"csv"
}
}
POST the request to the reporting service
$ curl -b cookies -c cookies -X POST -d @engagement_report_for_buyers 'https://api.appnexus.com/report'
{
"response":{
"status":"OK",
"report_id":"097f59fc3ab7d02c5d60db42081d9b69"
}
}
GET the report status from the report service
Make a GET call with the Report ID to retrieve the status of the report. Continue making this GET call until the execution_status is "ready". Then use the report-download service to save the report data to a file, as described in the next step.
$ curl -b cookies -c cookies 'https://api.appnexus.com/report?id=097f59fc3ab7d02c5d60db42081d9b69'
{
"response":{
"status":"OK",
"report":{
"name":null,
"created_on":"2021-05-25 19:19:53",
"json_request":"{\"report\":{\"report_type\":\"engagement_report_for_buyerss\",\"columns\":[\"line_item_id\",
\"line_item_name\",\"creative_name\",\"viewable_completion_rate\",\"average_viewable_duration\",\"ctr\",\"clicks\",\"imps\"],
\"report_interval\":\"last_7_days\"}}",
"url": "report-download?id=b97897a7864dd8f34e7457226c7af592"
},
"execution_status":"ready"
}
}
GET the report data from the report download service
To download the report data to a file, make another GET call with the Report ID, but this time to the report-download service. You can find the service and Report ID in the url field of the previous GET response. When identifying the file that you want to save to, be sure to use the file extension of the "format" that you specified in your initial POST.
Note
If an error occurs during download, the response header will include an HTTP error code and message. Use -i or -v in your call to expose the response header.
$ curl -b cookies -c cookies 'https://api.appnexus.com/report-download?id=b97897a7864dd8f34e7457226c7af592' > /tmp/engagement_report_for_buyers.csv