Advertiser creative frequency and recency

The Advertiser Creative Frequency & Recency report can be used to view creative data for a specific advertiser based on the frequency and recency of user views. This report is available to advertiser and network users.

For instructions on retrieving a report, please see Report Service or see the example below. For an advertiser user, the advertiser ID is detected based on the user's authentication. For a network user, however, this report requires specifying the advertiser ID as part of the URL, for example:

https://api.appnexus.com/report?advertiser_id=ADVERTISER_ID

Note

Lookback window

Frequency and recency data is available for 120 days (no data before February 26, 2017).

Time frame

The report_interval field in the JSON request can be set to one of the following:

• last_hour
• today
• yesterday
• last_48_hours
• last_2_days
• last_7_days
• last_14_days
• month_to_date
• last_30_days
• last_month
• last_100_days
• custom

Data retention period

Data retention period for this report is 120 days.

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
hour	time	No	"2010-02-01 06:00:00"	The hour of the auction.
day	time	No	"2010-02-01"	The day of the auction.
month	time	No	"2010-02"	The month of the auction.
creative_id	int	yes	554	The ID of the creative. 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. Note: For external click or impression trackers, creative_name will be "External Clicks" or "External Imps".
creative	string	no	"Q1 2010 728x90 (554)"	Deprecated (as of October 17, 2016).
creative_recency_bucket	string	yes	"15-30 minutes"	The bucket for how recently the creative was displayed. See Creative Recency Buckets below for possible values.
creative_recency_bucket_id	string	no	"4"	The ID of the creative recency bucket. See Creative Recency Buckets below for possible values.
creative_frequency_bucket	string	yes	"11-20"	The bucket for how frequently the creative was displayed. See Creative Frequency Buckets below for possible values.
creative_frequency_bucket_id	string	no	"3"	The ID of the creative frequency bucket. See Creative Frequency Buckets below for possible values.
buyer_member_id	int	Yes	123	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.
advertiser_id	int	Yes	789	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.
advertiser_name	string	No	"Verizon Wireless"	The name of the advertiser.
advertiser	string	No	"Verizon Wireless (789)"	Deprecated (as of October 17, 2016).
advertiser_code	string	No	"Virizon Wireless Code"	The custom code for the advertiser.
insertion_order_id	int	Yes	321	The ID of the insertion order.
insertion_order_name	string	No	"Insertion Order"	The name of the insertion order.
insertion_order	string	No	"Insertion Order (321)"	Deprecated (as of October 17, 2016).
insertion_order_code	string	No	"Insertion Order Code"	The custom code for the insertion order.
line_item_id	int	Yes	111	The ID of the line item.
line_item_name	string	No	"Default Line Item"	The name of the line item.
line_item	string	No	"Default Line Item (111)"	Deprecated (as of October 17, 2016).
line_item_code	string	No	"Default Line Item Code"	The custom code for the line item.
campaign_id	int	Yes	222	The ID of the campaign.
campaign_name	string	No	"Default Campaign"	The name of the campaign.
campaign	string	No	"Default Campaign (222)"	Deprecated (as of October 17, 2016).
campaign_code	string	No	"Default Campaign Code"	The custom code for the campaign.
campaign_priority	int	No	5	The bidding priority for a campaign that targets direct inventory. Possible values: 1 - 10, where 10 is the highest priority.
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	Yes	"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.
size	string	Yes	"728x90"	The size of the placement/creative served.
is_remarketing	int	yes	0, 1	Whether or not the campaign is remarketing
bid_type	string	Yes	"Manual"	The optimization phase the node was in when it bid for this impression. Note: The term "give up" is appended to the bid types below if the valuation for that impression falls below the venue's "give up price". Allowed values are: - "Manual": Applies when you are bidding with a CPM goal, whether it's Base, EAP, or ECP. - "Learn": Applies when you are bidding with optimization (CPA, CPC, or margin) and we do not yet have enough data to bid optimized. - "Optimized": Applies when you are bidding with optimization (CPA, CPC, or margin) and we have enough data to bid optimized. - "Unknown": The node was in an unknown optimization phase. - "Optimized give up" - "Learn give up" - "Manual give up"
media_type	string	No	"Banner", "Pop", "Interstitial", "Video", "Text", "Expandable", "Skin"	The general display style of a creative. You can use the Media Type Service to view the complete list of media types.
mediatype_id	int	Yes	1	The ID of the general display style of a creative.
user_group_for_campaign	string	Yes	"Test"	The test/control user group for the campaign. See the "labels" field in the Campaign Service for more details.

Metrics

Column	Type	Example	Formula	Description
imps	int	2340	imps	The total number of impressions (served and resold).
clicks	int	1	clicks	The total number of clicks across all impressions.
total_convs	int	9	post_click_convs + post_view_convs	The total number of post-view and post-click conversions.
convs_rate	double	0.000221877080097626	total_convs / imps	The rate of conversions to impressions.
click_convs_rate	double	0.1651376	total_convs / clicks	The rate of conversions to clicks.
click_conv_rate	double	0.000064	total_convs / clicks	The rate of conversions to clicks. Note: This field is identical to click_convs_rate.
ctr	double	0.000221877080097626	clicks / imps	The rate of clicks to impressions.
click_thru_pct	double	1.12359550561797%	(clicks / imps) x 100	The rate of clicks to impressions as a percentage.
post_click_convs	int	4	post_click_convs	The total number of recorded post-click conversions.
post_click_convs_rate	double	0.0002	post_click_convs / imps	The rate of post-click conversion to impressions.
post_click_revenue	money	150.00	post_click_revenue	The total amount of recorded post-click conversion revenue.
post_view_convs	int	5	post_view_convs	The total number of recorded post-view conversions.
post_view_convs_rate	double	0.00013	post_view_convs / imps	The rate of post-view conversions to impressions.
post_view_revenue	money	300.00	post_view_revenue	The total amount of recorded post-view conversion revenue.
media_cost	money	100	media_cost	The total amount spent

Creative frequency buckets

Bucket ID	Bucket Name
-2	"no-cookie-data" (cookie lookup failed)
-1	"no-cookie" (user does not have cookies enabled)
0	"0"
1	"1"
2	"2-5"
3	"6-10"
4	"11-20"
5	"21-40"
6	"41-60"
7	"61-100"
8	"101-150"
9	"151-250"
10	"251-500"
11	"500+"

Creative recency buckets

Bucket ID	Bucket Name
-2	"no-cookie-data" (cookie lookup failed)
-1	"no-cookie" (user does not have cookies enabled)
0	"< 1 minute"
1	"1-5 minutes"
2	"5-15 minutes"
3	"15-30 minutes"
4	"30-60 minutes"
5	"1-4 hours"
6	"4-12 hours"
7	"12-24 hours"
8	"1-2 days"
9	"2-7 days"
10	"8-14 days"
11	"14-30 days"

Example

Create a JSON-formatted report request

$ cat network_advertiser_frequency_recency {
    "report":
    {
        "report_type": "network_advertiser_frequency_recency",
        "columns": [
            "creative_recency_bucket",
            "creative_frequency_bucket",
            "creative_id",
            "imps",
            "clicks",
            "total_convs"
        ],
        "report_interval": "last_7_days",
        "emails": ["js@email.com"],
        "format": "csv"
    }
}

POST the request to the reporting service

$ curl -b cookies -c cookies -X POST -d @network_advertiser_frequency_recency "https://api.appnexus.com/report?advertiser_id=384"

{
    "response": {
        "status": "OK",
        "report_id": "c458f71c084a2a3b51dcd749132bcf87",
        "dbg_info": {
            ...
        }
    }
}

Use the report ID to retrieve the report data

The standard response includes the report data and a Download URL that you can us to save the data to a file. If you want to get just the Download URL without the report data, pass "without_data" in the query string.

$ curl -b cookies -c cookies "https://api.appnexus.com/report?id=c458f71c084a2a3b51dcd749132bcf87"

{
    "response": {
        "status": "OK",
        "report": {
            "name": null,
            "created_on": "2012-02-03 21:43:27",
            "cache_hit": true,
            "fact_cache_hit": false,
            "fact_cache_error": null,
            "json_request": "{\"report\":{\"report_type\":\"network_advertiser_frequency_recency\",
             \"columns\":[\"creative_recency_bucket\",\"creative_frequency_bucket\",\"creative_id\",
             \"imps\",\"clicks\",\"total_convs\"],\"report_interval\":\"last_7_days\",\"emails\":
             [\"js@email.com\"],\"filters\":[{\"buyer_member_id\":\"541\"},{\"advertiser_id\":
             \"3610\"}]}}",
            "header_info": null,
            "data": "creative_recency_bucket,creative_frequency_bucket,creative_id,imps,clicks,
             total_convs\r\nno-cookie,no-cookie,700454,47,0,0\r\n2-7 days,2-5,773422,31,0,
             0\r\n5-15 minutes,6-10,1298720,1,0,0\r\n14-30 days,151-250,700464,8,0,0\r\n7-14 days,
             21-40,711929,5,0,0\r\n1-4 hours,6-10,1317518,826,2,0\r\n1-4 hours,1,1317473,996,14,
             0\r\n12-24 hours,11-20,1317436,139,0,0\r\n15-30 minutes,6-10,773408,12,0,0\r\nno-cookie,
             no-cookie,1318994,3,0,0\r\n1-5 minutes,101-150,711932,898,0,0\r\n2-7 days,2-5,773408,45,
             0,0\r\n1-5 minutes,2-5,610381,7990,23,0\r\n12-24 hours,1,1316895,4790,30,0\r\n1-4 hours,
             ...
             "url": "report-download?id=c447d71c084a2a3b51dcd749132bcf87"
        },
        "execution_status": "ready",
        "dbg_info": {
            ...
        }
    }
}

Use the download URL to save the report data to a file

You use the "url" field in the response to save the report data to a file. Simply make another GET call and identify the location and file that you want to save to. Be sure to use the file the extension of the "format" that you specified in your initial POST request.

$ curl -b cookies -c cookies 'https://api.appnexus.com/report-download?id=c447d71c084a2a3b51dcd749132bcf87' > /tmp/network_advertiser_frequency_recency.csv

Note

There is a limit of 100,000 rows per report when you download them as XLSX and Excel file.