Advertiser Frequency report
Note
This service is currently available to a limited set of clients and Microsoft employees only.
The Advertiser Frequency report can be used to view how frequently users are viewing a specific advertiser's creatives. This report shows data at the advertiser level and is available to members.
For instructions on retrieving a report, see the example below.
Time frame
The report_interval
field in the JSON request can be set to one of the following:
last_48_hours
today
yesterday
last_7_days
month_to_date
last_24_hours
last_30_days
Dimensions
Column | Type | Description |
---|---|---|
hour |
time | The hour of the auction. Example: "2010-02-01 06:00:00" Group: Yes Filter: Yes |
day |
time | The day of the auction. Example: "2010-02-01" Group: Yes Filter: Yes |
month |
time | The month of the auction. Example: "2010-02" Group: Yes Filter: Yes |
buyer_member_id |
int | The ID of the buying member. If the impression was not purchased, this field shows one of the following values: 229 = PSA 0 = Blank 319 = Default.Example: 123 Group: Yes Filter: Yes |
insertion_order_id |
int | The ID of the insertion order. Group: Yes Filter: Yes |
advertiser_id |
int | The ID of the advertiser. If the value is 0 , either the impression was purchased by an external buyer, or a default or PSA was shown.Example: 789 Group: Yes Filter: Yes |
line_item_id |
int | The ID of the line item. Example: 111 Group: Yes Filter: Yes |
pixel_id |
int | The ID of the pixel. Example: 123 Group: Yes Filter: Yes |
advertiser_name |
string | The name of the advertiser. Example: "Verizon Wireless" Group: No Filter: No |
advertiser |
string | Deprecated (as of October 17, 2016). |
insertion_order_name |
string | The name of the insertion order. Group: No Filter: No |
insertion_order_code |
string | The custom code for the insertion order. Group: No Filter: No |
line_item_name |
string | The name of the line item. Example: "Default Line Item" Group: No Filter: No |
line_item_code |
string | The custom code for the line item. Group: No Filter: No |
insertion_order |
string | Deprecated (as of October 17, 2016). |
line_item |
string | Deprecated (as of October 17, 2016). |
advertiser_frequency_bucket |
string | The bucket for how frequently the advertiser's creatives were displayed. See Advertiser Frequency Buckets. Group: Yes Filter: Yes |
advertiser_frequency_bucket_id |
int | The ID of the advertiser frequency bucket. See Advertiser Frequency Buckets below for possible values. Group: No Filter: No |
Advertiser frequency buckets
Bucket ID | Bucket Name |
---|---|
-2 |
"no-cookie-data" |
-1 |
"no-cookie" |
0 |
"0" |
1 - 21 |
Bucket name is the number of times the advertiser's creatives have been viewed. |
21 |
"21-25" |
22 |
"26-30" |
23 |
"31-35" |
24 |
"36-40" |
25 |
"41-45" |
26 |
"46-50" |
27 |
"51-60" |
28 |
"61-70" |
29 |
"71-80" |
30 |
"81-90" |
31 |
"91-100" |
32 |
"101-200" |
33 |
"201-300 " |
34 |
"301-400" |
35 |
"401-500" |
36 |
"501+" |
Metrics
Column | Type | Description | Example | Formula |
---|---|---|---|---|
imps |
int | The total number of impressions (served and resold). | 2437 |
imps |
clicks |
int | The total number of clicks across all impressions. | 1 |
clicks |
booked_revenue |
money | The total revenue booked through direct advertisers (line item). | 25.6788 |
booked_revenue |
cpm |
money | The cost per 1000 impressions | 1.6605 |
(cost / imps) x 1000 |
total_convs |
int | The total number of post-view and post-click conversions. | 9 |
post_click_convs + post_view_convs |
convs_rate |
double | The rate of conversions to impressions. | 0.0002218770 |
total_convs / imps |
ctr |
double | The rate of clicks to impressions. | 0.0002218777 |
clicks / imps |
post_view_convs |
int | The total number of recorded post-view converstions. | 5 |
post_view_convs |
post_click_convs |
int | The total number of recorded post-click conversions. | 4 |
post_click_convs |
post_click_convs_rate |
double | The rate of post-click conversion to impressions. | 0.0002 |
post_click_convs / imps |
media_cost |
money | The total amount spent. | 100.00 |
media_cost |
profit_ecpm |
money | The profit as a percentage of the revenue. | 0.778 |
((booked_revenue - media_cost) / imps) * 100 |
revenue_ecpc |
money | The total revenue per click. | 0.8256 |
booked_revenue / clicks |
revenue_ecpa |
money | The total revenue per conversion. | 5.00 |
booked_revenue / total_convs |
cost_ecpc |
money | The cost per click. | 0.1834 |
media_cost / clicks |
cost_ecpa |
money | The cost per attribution/conversion. | 0.1834 |
media_cost / total_convs |
convs_per_mm |
double | The number of conversions per million impressions. | 221.87708 |
(total_convs / imps) x 1,000,000 |
Example
Step 1. Create a JSON report request
The JSON file should include the following:
"report_type"
you want to run."columns"
(dimensions and metrics) you want to retrieve."report_interval"
you want to retrieve.
You can also include filters
for dimensions, define granularity (year
, month
, day
), and specify the format
in which the data should be returned ( "csv"
, "excel"
, or "html"
).
To filter a dimension by more than one value, use an array. For example:
Note
Correct:
"filters": [{"bid_type": ["learn","optimized"]}, {"geo_country":"US"}]
Incorrect:
"filters": [{"bid_type":"learn"}, {"bid_type":"optimized"}, {"geo_country":"US"}]
See Dimensions and Metrics above for more details about the columns that can be included in the request.
The example below demonstrates how to retrieve the Advertiser Frequency Report. In this example, the report will display data for the hour
, campaign
, imps
, clicks
, total_convs
, ctr
, and convs_rate
columns. This report will pull data from the last 48 hours and will format it as a CSV file.
$ cat report_request
{
"report":{
"report_type":"advertiser_frequency",
"columns":[
"hour",
"line_item_id",
"imps",
"clicks",
"total_convs",
"ctr",
"convs_rate"
],
"report_interval":"last_48_hours",
"format":"csv"
}
}
Step 2.POST
the request to the report service
POST
the JSON request to get back a report_ID
.
$ curl -b cookies -X post -d @report_request "http://api.appnexus.com/report"
{
"response":{
"status":"OK",
"report_id":"09b6979a6a4c3805bdac8921378d3622"
}
}
Alternatively, you can get a report_id
via a POST
request using a saved_report_id
.
$ curl -b cookies -X POST 'http://api.appnexus.com/report?saved_report_id=30'
Step 3.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 'http://api.appnexus.com/report?id=09b6979a6a4c3805bdac8921378d3622'
{
"response":{
"status":"OK",
"report":{
"name":null,
"created_on":"2010-05-25 19:15:48",
"json_request":"{\"report\":{\"report_type\":\"network_advertiser_frequency\",\"columns\":
[\"hour\",\"line_item_id\",\"imps\",\"clicks\",\"total_convs\",
\"ctr\",\"convs_rate\"],\"row_per\":[\"hour\",\"campaign_id\"],
\"report_interval\":\"last_48_hours\",\"filters\":[{\"advertiser_id\":\"690\"}]}}",
"url":"report-download?id=b97897a7864dd8f34e7457226c7af592"
},
"execution_status":"ready"
}
}
Step 4. 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 response to your previous GET
call. When setting the file to which you want to save the report, use the file extension of the "format"
(e.g., .csv) 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 'http://api.appnexus.com/report-download?id=b97897a7864dd8f34e7457226c7af592' -o /tmp/network_advertiser_frequency.csv