Digital Platform API - Publisher Analytics

The Publisher Analytics report can be used to view revenue and profit data across a specific publisher's sites and placements. This report is available to both network and publisher users.

For instructions on retrieving a report, see the Report Service or the examples below. This report requires that a publisher ID be specified as part of the URL as follows:

https://api.appnexus.com/report?publisher_id=PUBLISHER_ID

Time frame

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

  • current_hour
  • last_hour
  • today
  • yesterday
  • last_48_hours
  • last_7_days
  • last_30_days
  • month_to_date
  • month_to_yesterday
  • quarter_to_date
  • last_month
  • lifetime

Data retention period

Most data in this report is maintained permanently (exceptions noted below). After:

  • 100 days, you are no longer able to report on hourly data. However, daily, monthly and cumulative intervals are still available.
  • 14 months, you are no longer able to report on individual:
    • Creatives
    • Placements
    • Brands

In some cases Analytics reports can show delivery that does not match Lifetime QuickStats for a given advertiser or publisher. This is due to the way that Analytics reporting data older than 100 days and 14 months are aggregated. The data from Billing reports are kept in non-aggregated form indefinitely.

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.

Note: For impressions older than 100 days, the day will be returned rather than the hour.
day time no "2010-02-01" The day of the auction.
month time no "2010-02" The month of the auction.
publisher_id int yes 923 The ID of the publisher.
publisher_code string no "My Publisher Code" The custom code for the publisher.
publisher_currency string no "USD" The currency of the publisher.
pub_rule_id int yes 736 The ID of the publisher rule.
pub_rule_name string no "My Publisher Rule" The name of the publisher rule.
pub_rule string no "My Publisher Rule (736)" Deprecated (as of October 17, 2016).
pub_rule_code string no "My Publisher Rule Code"
seller_member_id int yes 456 The ID of the selling member.
geo_country string yes "US" The code of the geographical country.
geo_country_name string no "United States" The name of the geographical country.
size string yes "728x90" The size of the placement/creative served.
placement_id int yes 546 The ID of the placement.

Note: For impressions older than 100 days, placements will be aggregated into one row with -1 as the placement_id.
placement_name string no "300x250 Business" The name of the placement. Note that, for impressions older than 100 days, placements will be aggregated into one row with "All placement data older than 100 days" as the placement_name.
placement string no "Photos 728x90 (567)" Deprecated (as of October 17, 2016).
placement_code string no "Photos Code"
deal_id int Yes 2345 The ID of the deal. For more information about deals you have negotiated with buyers, see Deal Service.
deal_name string No "Private deal for buyer 1085 with floor of $2.50" The name of the deal.
deal string No "Private deal for buyer 1085 with floor of $2.50 (45)" Deprecated (as of October 17, 2016).
deal_code string No "Custom code" The custom code for the deal.
brand_id int yes 3 The ID of the brand associated with a creative served on the publisher's inventory. For imp_type_id = 6, no information is available in the brand_id field for this report. See the Publisher Brand Review Report instead.
brand_name string no "Ace Hardware" The name of the brand associated with a creative served on the publisher's inventory. For imp_type_id = 6, no information is available in the brand_name field for this report. See the Publisher Brand Review Report instead.
brand string no "Ace Hardware (3)" Deprecated (as of October 17, 2016).
supply_type string no The type of inventory. Possible values:
- "web"
- "mobile_web"
- "mobile_app"
imp_type_id int yes 1 The ID for the type of impression. Possible values (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.
imp_type name yes "Kept" The type of impressions. For possible values see imp_type_id.
media_type string no "Banner", "Pop", "Interstitial", "Video", "Text", "Expandable", "Skin" The general display style of a creative served on the publisher's inventory. You can use the Media Type Service to view the complete list of media types.
adjustment_id int yes 22 The ID of an adjustment you have set using the Adjustment Service. Networks use adjustments to help display their actual revenue in Xandr reporting.
site_id int yes 555 The ID of the site. For more information, see the Site Service.
site_name string yes "My Site" The name of the site. For more information, see the Site Service.
site string yes "My Site (555)" Deprecated (as of October 17, 2016).
venue string yes "Venue 55" The word Venue followed by the ID of the inventory's associated venue.
mediatype_id int yes 444 The ID of the media type associated with the creative that was served. For more information, see the Media Type Service.

Metrics

Column Type Example Formula Description
imps_total int 234223 imps The total number of impressions (including defaults).
imps_requests int 234300 imps_requests The total number of ad calls (impression requests).

Warning: This metric is typically inaccurate for video inventory due to occasional delays in receiving video events, which can lead to inflated request totals based on the assumption that the video has expired. For a better video request metric, you should use Ad Requests in the Seller Fill and Delivery Network Report or the Network Video Analytics Report.
imps_sold int 234123 imps_sold The total number of impressions sold to direct and real-time advertisers.
imps_default int 100 imps_default The total number of impressions not sold (default creative served).
imps_blank int 12 imps_blank The number of impressions which were served with a blank.
imps_psa int 10 imps_psa The number of impressions which were served with a PSA.
imps_default_error int 3 imps_default_error The number of impressions which defaulted due to a timeout error.
imps_default_bidder int 5 imps_default_bidder The number of impressions which defaulted because there were no valid bids.
imps_kept int 405 imps_kept The number of impressions your advertiser purchased from your publisher.
imps_resold int 506 imps_resold The number of impressions your publisher sold to a third party.
imps_rtb int 94 imps_rtb The number of impressions your advertiser bought from a third party.
imps_filled int 4900 imps_filled The number of blank, PSA, default, kept, resold, and external impressions.
external_impression int 0 external_impression The number of external impressions.
external_click int 0 external_click The number of external clicks.
clicks int 545 clicks The total number of clicks across all impressions.
post_view_convs_pixel int 23 Post view conversions for the pixel. For more information on how we attribute post-view (and other) conversions, see Conversion Attribution (Microsoft Monetize) or Conversion Attribution (Microsoft Invest).
post_clicks_convs_pixel int 15 Post click conversions for the pixel. For more information on how we attribute post-view (and other) conversions, see Conversion Attribution (Microsoft Monetize) or Conversion Attribution (Microsoft Invest).
publisher_revenue money 400.05 publisher_revenue The revenue paid out to the publisher (based on revshare or CPM).
publisher_revenue_pub_curr money 400.05 publisher_revenue_pub_curr The revenue paid out to the publisher (based on revshare or CPM), in the currency of the publisher.
publisher_filled_revenue money 350.02 publisher_filled_revenue The revenue paid out to the publisher (based on revshare or CPM) for filled impressions.
publisher_filled_revenue_publisher_curr money 350.02 publisher_filled_revenue The revenue paid out to the publisher (based on revshare or CPM) for filled impressions, in the currency of the publisher.
publisher_default_revenue money 350.02 publisher_default_revenue The revenue paid out to the publisher (based on revshare or CPM) for default impressions.
publisher_default_revenue_publisher_curr money 350.02 publisher_default_revenue The revenue paid out to the publisher (based on revshare or CPM) for default impressions, in the currency of the publisher.
total_convs int 205 total_convs The total number of post view and post click conversions.
ctr double 0.002327 clicks / imps The rate of clicks to impressions.
click_thru_pct double 1.12359550561797 (clicks / imps) * 100 The rate of clicks to impressions as a percentage.
convs_rate double 0.000856 total_convs / imps The rate of conversions to impressions.
convs_per_mm double 221.877080097625 (total_convs / imps) x 1,000,000 The number of conversions per million impressions.
publisher_rpm money 1.71 (publisher_revenue / imps) x 1000 The publisher revenue per 1000 impressions.
publisher_rpm_pub_curr money 1.71 (publisher_revenue / imps) x 1000 The publisher revenue per 1000 impressions, in the currency of the publisher.
publisher_filled_rpm money (publisher_revenue / imps_filled) x 1000 The publisher revenue per 1000 filled impressions.
publisher_filled_rpm_publisher_currency money (publisher_revenue / imps_filled) x 1000 The publisher revenue per 1000 filled impressions, in the publisher's currency.
publisher_default_rpm money 1.71 (publisher_revenue / imps_default) x 1000 The publisher revenue per 1000 default impressions.
publisher_default_rpm_publisher_curr money 1.71 (publisher_revenue / imps_default) x 1000 The publisher revenue per 1000 default impressions, in the currency of the publisher.
imps_viewed int 30,450 imps_viewed The number of measured impressions that were viewable, per the IAB Viewability definition, which states that an impression is viewable if 50% of the pixels are in-view during 1 consecutive second.
view_measured_imps int 10,120 view_measured_imps The total number of impressions that were measured for viewability.
view_rate double 58% view_rate The percentage of impressions that were viewable out of the total number of impressions measured for viewability. (Viewed Imps / View Measured Imps)
view_measurement_rate double 45% view_measurement_rate The percentage of impressions measured for viewability out of the total number of impressions. (View Measured Imps / Imps)
video_skips int 10 The total number of times a user skipped the video. Use this metric for reporting when buying skippable inventory.
video_starts int 11 The total number of times the first segment of the video creative was downloaded and started.
video_25_pcts int 10 The total number of times the video creatives completed 25% of the entire duration.
video_50_pcts int 10 The total number of times the video creatives completed 50% of the entire duration.
video_75_pcts int 10 The total number of times the video creatives completed 75% of the entire duration.
video_completions int 12 The total number of times the video creatives played for the entire duration.
video_served int 10 The total number of video responses served to the player.An ad response occurs when the VAST document (XML) is served in response to a request.An ad response doesn't necessarily indicate a successful impression. For an impression, the first frame of the video must be served.
video_errors int 2 The total number of times a video error occurred.
revenue_per_video_complete money 25.76 The revenue per video completion.
cost_per_video_complete money 22.76 The cost per video completion.
video_completion_rate double 1.12359550561797% (video completions/total impressions) x 100 The ratio of video completions to impressions, expressed as a percentage.
video_start_rate double 1.12359550561797% The percentage of times the first segment of the video creative was downloaded and started.
video_skip_rate double 1.12359550561797% The percentage of times the user opted to skip the video.

Age buckets

Bucket ID Bucket Name
0 "unknown"
1 "13-17"
2 "18-24"
3 "25-34"
4 "35-44"
5 "45-54"
6 "'55-64"
7 "65+"

Examples

Step 1: Prepare your report request

$ cat the-file.json

{
    "report": {
        "format": "csv",
        "report_interval": "yesterday",
        "columns": [
            "publisher_id",
            "imp_type",
            "geo_country",
            "placement_id",
            "imps_total",
            "imps_kept",
            "imps_resold",
            "publisher_filled_revenue",
            "total_convs"
        ],
        "report_type": "publisher_analytics"
    }
}

Step 2: POST the request JSON to the report service

$ curl -b cookies -c cookies -X POST -d @the-file.json 'https://api.appnexus.com/report?publisher_id=5555'

{
    "response": {
        "status": "OK",
        "report_id": "f589854c1697da8ff9ead66825c9bc04"
    }
}

Step 3: Check the status of your request

$ curl -b cookies 'https://api.appnexus.com/report?id=f589854c1697da8ff9ead66825c9bc04'

{
    "response": {
        "status": "OK",
        "report": {
            "name": "",
            "created_on": "2013-10-30 21:15:36",
            "cache_hit": false,
            "fact_cache_hit": false,
            "fact_cache_error": "",
            "header_info": "",
            "row_count": "",
            "report_size": "",
            "internal_info": "",
            "user_id": "2027",
            "entity_id": "0",
            "started_on": "1970-01-01 00:00:01",
            "finished_on": "1970-01-01 00:00:01",
            "query_time": ""
        },
        "execution_status": "pending"
    }
}

Step 4: Download your data

curl -b cookies 'https://api.appnexus.com/report-download?id=f589854c1697da8ff9ead66825c9bc04' > /tmp/publisher_analytics.csv

Note

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